shiplog 0.1.1 → 0.3.0

data/lib/shiplog/classes.rb

@@ -7,9 +7,12 @@ module Shiplog
       page_header: "shiplog-page__header",
       page_title: "shiplog-page__title",
       page_lede: "shiplog-page__lede",
+      switcher: "shiplog-switcher",
+      switcher_link: "shiplog-switcher__link",
       columns: "shiplog-columns",
       column: "shiplog-column",
       column_header: "shiplog-column__header",
+      column_marker: "shiplog-column__marker",
       column_title: "shiplog-column__title",
       column_count: "shiplog-column__count",
       column_description: "shiplog-column__description",
@@ -18,6 +21,16 @@ module Shiplog
       card: "shiplog-card",
       card_title: "shiplog-card__title",
       card_body: "shiplog-card__body",
+      card_meta: "shiplog-card__meta",
+      card_tag: "shiplog-card__tag",
+      shipped: "shiplog-shipped",
+      shipped_title: "shiplog-shipped__title",
+      shipped_list: "shiplog-shipped__list",
+      shipped_item: "shiplog-shipped__item",
+      shipped_date: "shiplog-shipped__date",
+      shipped_link: "shiplog-shipped__link",
+      footnote: "shiplog-footnote",
+      footnote_link: "shiplog-footnote__link",
       months: "shiplog-months",
       month: "shiplog-month",
       month_title: "shiplog-month__title",
@@ -30,7 +43,22 @@ module Shiplog
       entry_date: "shiplog-entry__date",
       pagination: "shiplog-pagination",
       pagination_link: "shiplog-pagination__link",
-      empty: "shiplog-empty"
+      empty: "shiplog-empty",
+      search: "shiplog-search",
+      search_input: "shiplog-search__input",
+      search_button: "shiplog-search__button",
+      search_summary: "shiplog-search__summary",
+      search_clear: "shiplog-search__clear",
+      search_empty: "shiplog-search__empty",
+      permalink: "shiplog-permalink",
+      permalink_back: "shiplog-permalink__back",
+      permalink_nav: "shiplog-permalink__nav",
+      permalink_nav_link: "shiplog-permalink__nav-link",
+      areas: "shiplog-areas",
+      area_link: "shiplog-areas__link",
+      entry_area: "shiplog-entry__area",
+      entry_images: "shiplog-entry__images",
+      entry_image: "shiplog-entry__image"
     }.freeze
 
     KEYS = BEM.keys.freeze

data/lib/shiplog/configuration.rb

@@ -1,16 +1,166 @@
 module Shiplog
   class Configuration
-    attr_accessor :repositories, :github_token, :webhook_secret,
+    attr_accessor :github_token, :webhook_secret,
       :public_label, :soon_labels, :excluded_labels, :excluded_authors, :commit_types,
       :rewriter, :product_name, :audience, :tone, :prompt_builder,
       :public_layout, :admin_layout,
       :stylesheet, :admin_flash, :authorize_admin, :current_admin,
-      :roadmap_path, :changelog_path
+      :roadmap_path
 
     ADMIN_CHROMES = %i[standalone hosted].freeze
+    # Segments of only dots ("." and "..") are path traversal, not names.
+    REPOSITORY_NAME = %r{\A(?!\.+/)[\w.-]+/(?!\.+\z)[\w.-]+\z}
+    REPOSITORY_OPTION_KEYS = %i[name changelog gem].freeze
+
+    attr_reader :repositories
+    # Path of the lockfile read in merged pull requests to detect gem upgrades (see config.repositories `gem:`).
+    attr_accessor :lockfile_path
+
+    # The public changelog's path: segments of a-z, 0-9, dashes and underscores, joined by slashes ("changelog",
+    # "docs/whats_new"); surrounding slashes are stripped. Permalinks live below it and the Atom feed is
+    # "<path>.atom". Read when routes are drawn.
+    attr_reader :changelog_path
+    CHANGELOG_PATH = %r{\A[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*\z}
+
+    # The site's canonical origin, e.g. "https://trackberry.com" (nil by default). When set, the Atom feed's ids
+    # and links, entry links, og:url and the other absolute URLs use it instead of the request's host, which
+    # varies (apex and www, a forged X-Forwarded-Host). An origin only: scheme, host and optional port. Any path
+    # prefix of the engine's mount comes from the routes, so it needs no place here.
+    attr_reader :canonical_url
 
     attr_reader :admin_chrome, :classes, :public_parent_controller, :admin_parent_controller
 
+    # Product updates navigation and roadmap options.
+    attr_accessor :feedback_path
+    # Whether the public changelog has a search box and honours ?q= (default true).
+    attr_accessor :changelog_search
+    # Called with the controller on each changelog index or permalink view (200 or 304 answers), e.g. to stamp
+    # the visitor's "last seen" time. It runs BEFORE the page renders (so a badge in the same response is
+    # current), on every visit, and may write: keep it cheap, e.g. write only when the stored time is older than
+    # the newest entry. Nil by default. Not part of the ETag: it doesn't change the markup.
+    attr_reader :on_changelog_seen
+    # Bump it when the output of a callable you configured changes (extra_pages, repository_labels, feedback_path):
+    # callables cannot be part of the ETag, so this is how cached public pages learn about it.
+    attr_accessor :cache_version
+    attr_reader :extra_pages, :repository_labels, :roadmap_shipped_count
+    # How many product areas the AI may create (default 8). Past it, entries can only join existing areas.
+    # Not part of render_digest: the markup depends on the areas themselves, which the ETag carries.
+    attr_reader :max_areas
+    # Screenshots in entries. `images` (default true) is effective only when Active Storage is loaded in the host
+    # (see Shiplog.images?). `max_images_per_entry` (default 4) caps the images fetched from GitHub per entry.
+    attr_reader :images, :max_images_per_entry
+    LOCALE_FORMAT = /\A[A-Za-z][A-Za-z0-9_-]*\z/
+
+    EXTRA_PAGE_KEYS = %i[label path].freeze
+
+    # A path (not "//host", "/\host" or "/ x", which browsers read as other targets), an http(s) URL or mailto:.
+    SAFE_URL = %r{\A(?:/(?![/\\\s])|https?://|mailto:)}i
+
+    # Whether a link target is safe to render: a path, an http(s) URL or a mailto: address.
+    def self.safe_url?(value)
+      value.is_a?(String) && SAFE_URL.match?(value.strip) && !value.match?(/[[:cntrl:]]/)
+    end
+
+    # A digest of everything configured that changes the public markup, stable across processes and servers
+    # (no Object#hash). Callables are represented by a marker; see cache_version.
+    def render_digest
+      stable = ->(value) { value.respond_to?(:call) ? "callable" : value }
+      data = [
+        classes.sort_by { |key, _| key.to_s }.map { |key, value| [ key.to_s, Array(value).map(&:to_s) ] },
+        stylesheet, roadmap_shipped_count, cache_version, product_name, canonical_url,
+        extra_pages.map { |page| [ stable.(page[:label]), stable.(page[:path]) ] },
+        repository_labels.sort_by { |name, _| name.to_s }.map { |name, label| [ name, stable.(label) ] },
+        stable.(feedback_path), changelog_search, images, max_images_per_entry, locales
+      ]
+      Digest::SHA256.hexdigest(JSON.generate(data))
+    end
+
+    # Pages added to the switcher after Roadmap and Changelog: [{ label:, path: }]. Each is a String, or a callable
+    # evaluated in the view (instance_exec), e.g. `path: -> { main_app.news_path }`.
+    def extra_pages=(value)
+      raise ArgumentError, "extra_pages must be an Array of { label:, path: } Hashes, got #{value.inspect}" unless value.nil? || value.is_a?(Array)
+      pages = (value || []).map do |page|
+        raise ArgumentError, "Each extra page must be a Hash with :label and :path, got #{page.inspect}" unless page.is_a?(Hash)
+        page = page.to_h.transform_keys { |key| key.to_s.to_sym }
+        unless page.keys.sort == EXTRA_PAGE_KEYS
+          raise ArgumentError, "An extra page needs exactly the keys :label and :path, got #{page.keys.inspect}"
+        end
+        page.each do |key, item|
+          valid = item.respond_to?(:call) || (item.is_a?(String) && item.present?)
+          raise ArgumentError, "Extra page #{key} must be a non-empty String or a callable, got #{item.inspect}" unless valid
+          if key == :path && item.is_a?(String) && !self.class.safe_url?(item)
+            raise ArgumentError, "Extra page path must be relative (/...), http(s):// or mailto:, got #{item.inspect}"
+          end
+        end
+        { label: page[:label], path: page[:path] }.freeze
+      end
+      @extra_pages = pages.freeze
+    end
+
+    # Display names for repositories on roadmap cards: { "owner/name" => "iPhone & iPad" }. Values are Strings or
+    # callables evaluated in the view.
+    def repository_labels=(value)
+      labels = value.nil? ? {} : value
+      raise ArgumentError, "repository_labels must be a Hash, got #{value.inspect}" unless labels.is_a?(Hash)
+      labels.each do |name, label|
+        unless label.respond_to?(:call) || label.is_a?(String)
+          raise ArgumentError, "repository_labels[#{name.inspect}] must be a String or a callable, got #{label.inspect}"
+        end
+      end
+      @repository_labels = labels.transform_keys(&:to_s).freeze
+    end
+
+    # How many recently shipped changelog entries the roadmap lists; 0 hides the section.
+    def roadmap_shipped_count=(value)
+      raise ArgumentError, "roadmap_shipped_count must be a non-negative Integer, got #{value.inspect}" unless value.is_a?(Integer) && value >= 0
+      @roadmap_shipped_count = value
+    end
+
+    def max_areas=(value)
+      raise ArgumentError, "max_areas must be a non-negative Integer, got #{value.inspect}" unless value.is_a?(Integer) && value >= 0
+      @max_areas = value
+    end
+
+    def images=(value)
+      raise ArgumentError, "images must be true or false, got #{value.inspect}" unless [ true, false ].include?(value)
+      @images = value
+    end
+
+    def max_images_per_entry=(value)
+      raise ArgumentError, "max_images_per_entry must be a non-negative Integer, got #{value.inspect}" unless value.is_a?(Integer) && value >= 0
+      @max_images_per_entry = value
+    end
+
+    # Locales entries are translated into when approved, e.g. [:es] (default none), as symbols and without the
+    # default locale (I18n.default_locale, read each time so an initializer that sets it later still counts): it
+    # is the language entries are written in. See Shiplog::Translator.
+    def locales = @locales - [ I18n.default_locale.to_sym ]
+
+    # Sets the locales to translate into: an Array of locale Symbols or Strings (see #locales).
+    def locales=(value)
+      unless value.is_a?(Array) && value.all? { |item| (item.is_a?(Symbol) || item.is_a?(String)) && LOCALE_FORMAT.match?(item.to_s) }
+        raise ArgumentError, "locales must be an Array of locale Symbols or Strings like [:es, \"pt-BR\"], got #{value.inspect}"
+      end
+      @locales = value.map(&:to_sym).uniq.freeze
+    end
+
+    def changelog_path=(value)
+      path = value.gsub(%r{\A/+|/+\z}, "") if value.is_a?(String)
+      unless path && CHANGELOG_PATH.match?(path)
+        raise ArgumentError, "changelog_path must be a path of letters, digits, dashes and underscores, with / between segments (like \"changelog\"), got #{value.inspect}"
+      end
+      @changelog_path = path
+    end
+
+    def canonical_url=(value)
+      @canonical_url = normalize_canonical_url(value)
+    end
+
+    def on_changelog_seen=(value)
+      raise ArgumentError, "on_changelog_seen must be nil or a callable, got #{value.inspect}" unless value.nil? || value.respond_to?(:call)
+      @on_changelog_seen = value
+    end
+
     # :standalone (default) wraps the admin in Shiplog's own page chrome; :hosted renders it inside the
     # layout of config.admin_layout (compact sub-nav, no page chrome of its own).
     def admin_chrome=(value)
@@ -44,8 +194,17 @@ module Shiplog
       @admin_parent_controller = value
     end
 
+    # Strings ("owner/name") or Hashes: { name:, changelog: true, gem: nil }. `changelog: false` keeps a repository
+    # on the roadmap but never drafts changelog entries from its pull requests or commits. `gem:` is the gem's
+    # name in the host's lockfile.
+    def repositories=(value)
+      warn_double_drafting(normalize_repositories(value))
+      @repositories = value
+    end
+
     def initialize
       @repositories = []
+      @lockfile_path = "Gemfile.lock"
       @public_label = "public"
       @soon_labels = %w[soon]
       @excluded_labels = %w[internal dependencies refactor chore]
@@ -64,6 +223,14 @@ module Shiplog
       @current_admin = ->(controller) { controller.try(:current_user)&.try(:email) }
       @roadmap_path = "roadmap"
       @changelog_path = "changelog"
+      @extra_pages = [].freeze
+      @repository_labels = {}.freeze
+      @roadmap_shipped_count = 4
+      @changelog_search = true
+      @max_areas = 8
+      @images = true
+      @max_images_per_entry = 4
+      @locales = [].freeze
     end
 
     def resolved_github_token
@@ -73,7 +240,27 @@ module Shiplog
     # The configured spelling of a repository name (matched case-insensitively), or nil.
     def repository_configured?(name)
       return if name.blank?
-      repositories.find { |configured| configured.casecmp?(name.to_s) }
+      repository_names.find { |configured| configured.casecmp?(name.to_s) }
+    end
+
+    # Normalised options of every configured repository: [{ name:, changelog:, gem: }].
+    def repository_entries = normalize_repositories(repositories)
+
+    def repository_names = repository_entries.map { |entry| entry[:name] }
+
+    def repository_options(name)
+      return if name.blank?
+      repository_entries.find { |entry| entry[:name].casecmp?(name.to_s) }
+    end
+
+    # False for roadmap-only repositories. Unknown repositories count as changelog sources.
+    def changelog_repository?(name)
+      repository_options(name)&.fetch(:changelog) != false
+    end
+
+    # { "gem name in the lockfile" => "owner/name" } for repositories with `gem:`.
+    def tracked_gems
+      repository_entries.select { |entry| entry[:gem] }.to_h { |entry| [ entry[:gem], entry[:name] ] }
     end
 
     def excluded_author?(login)
@@ -82,6 +269,61 @@ module Shiplog
 
     private
 
+    def normalize_canonical_url(value)
+      return if value.nil? || (value.is_a?(String) && value.strip.empty?)
+      raise ArgumentError, "canonical_url must be a String like \"https://example.com\", got #{value.inspect}" unless value.is_a?(String)
+
+      uri = begin
+        URI.parse(value.strip)
+      rescue URI::InvalidURIError
+        nil
+      end
+      valid = uri.is_a?(URI::HTTP) && uri.host.present? && [ "", "/" ].include?(uri.path) && uri.query.nil? && uri.fragment.nil? && uri.userinfo.nil?
+      raise ArgumentError, "canonical_url must be an http(s) origin without path, query or credentials (\"https://example.com\"), got #{value.inspect}" unless valid
+
+      port = ":#{uri.port}" unless uri.port == uri.default_port
+      "#{uri.scheme}://#{uri.host.downcase}#{port}"
+    end
+
+    def normalize_repositories(value)
+      raise ArgumentError, "config.repositories must be an Array, got #{value.inspect}" unless value.is_a?(Array)
+
+      value.map { |item| normalize_repository(item) }
+    end
+
+    # A gem repository that also drafts its own changelog entries announces each change twice: once from its own
+    # pull requests and once from the host's upgrade pull request.
+    def warn_double_drafting(entries)
+      entries.select { |entry| entry[:gem] && entry[:changelog] }.each do |entry|
+        Rails.logger&.warn("[shiplog] Repository #{entry[:name]} has gem: #{entry[:gem].inspect} and changelog: true, so its changes " \
+          "are drafted twice (from its own pull requests and from the host's upgrade pull request). Set changelog: false.")
+      end
+    end
+
+    def normalize_repository(item)
+      return { name: valid_repository_name!(item), changelog: true, gem: nil } if item.is_a?(String) && item.present?
+      raise ArgumentError, "Invalid repository #{item.inspect}: expected \"owner/name\" or a Hash" unless item.is_a?(Hash)
+
+      options = item.transform_keys { |key| key.to_s.to_sym }
+      unknown = options.keys - REPOSITORY_OPTION_KEYS
+      raise ArgumentError, "Unknown repository option(s) #{unknown.map(&:inspect).join(", ")}. Valid: #{REPOSITORY_OPTION_KEYS.map(&:inspect).join(", ")}" if unknown.any?
+
+      name, changelog, gem = options.values_at(:name, :changelog, :gem)
+      changelog = true if changelog.nil?
+      raise ArgumentError, "Repository #{item.inspect} needs a :name (\"owner/name\")" unless name.is_a?(String) && name.present?
+      valid_repository_name!(name)
+      raise ArgumentError, "Repository #{name}: changelog must be true or false" unless [ true, false ].include?(changelog)
+      raise ArgumentError, "Repository #{name}: gem must be a non-empty String" unless gem.nil? || (gem.is_a?(String) && gem.present?)
+
+      { name:, changelog:, gem: }
+    end
+
+    def valid_repository_name!(name)
+      raise ArgumentError, "Invalid repository name #{name.inspect}: expected \"owner/name\"" unless REPOSITORY_NAME.match?(name)
+
+      name
+    end
+
     def ensure_controller_not_loaded!(setting, namespace, name)
       return unless namespace.const_defined?(name, false) && !namespace.autoload?(name)
 

data/lib/shiplog/engine.rb

@@ -1,5 +1,8 @@
 module Shiplog
   class Engine < ::Rails::Engine
     isolate_namespace Shiplog
+
+    # Once per boot, after the host's initializers have set config.images: say why screenshots are off.
+    config.after_initialize { Shiplog.log_images_status }
   end
 end

data/lib/shiplog/github/client.rb

@@ -6,6 +6,7 @@ module Shiplog
   module Github
     class Client
       ENDPOINT = URI("https://api.github.com/graphql")
+      REST_ROOT = "https://api.github.com".freeze
       RETRYABLE_STATUSES = [ 502, 503, 504 ].freeze
       NETWORK_ERRORS = [
         Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED,
@@ -25,40 +26,72 @@ module Shiplog
         handle(response)
       end
 
+      # REST GET (e.g. "/repos/owner/name/compare/a...b") with the same auth, errors and rate-limit
+      # handling as #query. Returns the parsed JSON body; a 404 raises NotFound.
+      def get(path)
+        raise Error, "No GitHub token configured (Shiplog.config.github_token)" if @token.blank?
+
+        uri = URI("#{REST_ROOT}#{path}")
+        response = perform(retried: false) { build_get(uri) }
+        check_status(response)
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise Error, "GitHub returned an unparseable response"
+      end
+
       private
 
-      def post(payload, retried: false)
-        response = request(payload)
+      def post(payload) = perform(retried: false) { build_request(payload) }
+
+      def perform(retried:, &build)
+        response = request(build.call)
         return response unless RETRYABLE_STATUSES.include?(response.code.to_i) && !retried
 
         sleep @retry_delay
-        post(payload, retried: true)
+        perform(retried: true, &build)
       end
 
-      def request(payload)
-        http = Net::HTTP.new(ENDPOINT.host, ENDPOINT.port)
+      def request(http_request)
+        uri = http_request.uri
+        http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = true
         http.open_timeout = 10
         http.read_timeout = 30
-        http.request(build_request(payload))
+        http.request(http_request)
       rescue *NETWORK_ERRORS => error
         raise Transient, "#{error.class}: #{error.message}"
       end
 
       def build_request(payload)
         Net::HTTP::Post.new(ENDPOINT).tap do |req|
-          req["Authorization"] = "Bearer #{@token}"
+          authorize(req)
           req["Content-Type"] = "application/json"
-          req["User-Agent"] = "shiplog/#{Shiplog::VERSION}"
           req.body = payload
         end
       end
 
-      def handle(response)
+      def build_get(uri)
+        Net::HTTP::Get.new(uri).tap do |req|
+          authorize(req)
+          req["Accept"] = "application/vnd.github+json"
+        end
+      end
+
+      def authorize(req)
+        req["Authorization"] = "Bearer #{@token}"
+        req["User-Agent"] = "shiplog/#{Shiplog::VERSION}"
+      end
+
+      def check_status(response)
         status = response.code.to_i
         raise_rate_limited(response) if rate_limited?(response, status)
         raise Transient, "GitHub responded with HTTP #{status}" if status >= 500
+        raise NotFound, "GitHub responded with HTTP 404" if status == 404
         raise Error, "GitHub responded with HTTP #{status}" unless status.between?(200, 299)
+      end
+
+      def handle(response)
+        check_status(response)
 
         body = JSON.parse(response.body)
         errors = body["errors"].to_a

data/lib/shiplog/github/errors.rb

@@ -5,6 +5,9 @@ module Shiplog
     # Network failures and 5xx responses; safe to retry later.
     class Transient < Error; end
 
+    # HTTP 404: the resource does not exist, or the token cannot see it.
+    class NotFound < Error; end
+
     class RateLimited < Error
       attr_reader :reset_at
 

data/lib/shiplog/github/queries.rb

@@ -27,6 +27,9 @@ module Shiplog
       PULL_REQUEST_WITH_ISSUES = <<~GRAPHQL.freeze
         fragment PullRequestWithIssues on PullRequest {
           ...PullRequestFields
+          baseRefOid
+          mergeCommit { oid parents(first: 1) { nodes { oid } } }
+          files(first: 100) { pageInfo { hasNextPage } nodes { path } }
           closingIssuesReferences(first: 20) {
             pageInfo { hasNextPage }
             nodes { id }
@@ -102,7 +105,47 @@ module Shiplog
         }
       GRAPHQL
 
-      ALL = { ISSUES:, PULL_REQUESTS:, ISSUE:, PULL_REQUEST:, COMMITS: }.freeze
+      # A file's text at a commit (`$expression` is "<oid>:<path>"); `object` is null when the file is absent.
+      BLOB_TEXT = <<~GRAPHQL.freeze
+        query($owner: String!, $name: String!, $expression: String!) {
+          repository(owner: $owner, name: $name) {
+            object(expression: $expression) {
+              ... on Blob { text isTruncated }
+            }
+          }
+        }
+      GRAPHQL
+
+      # The pull requests that introduced each commit (`$ids` are commit node ids, at most 100).
+      COMMIT_PULL_REQUESTS = <<~GRAPHQL.freeze
+        query($ids: [ID!]!) {
+          nodes(ids: $ids) {
+            ... on Commit {
+              oid
+              associatedPullRequests(first: 5) {
+                nodes {
+                  number title body url state
+                  repository { nameWithOwner }
+                }
+              }
+            }
+          }
+        }
+      GRAPHQL
+
+      # The rendered HTML of one issue or pull request body (`$id` is its node id). Kept out of the sync documents so
+      # their payloads don't grow: it is only asked for when a draft is written, to find screenshots. On private
+      # repositories its <img src> URLs are short-lived signed URLs.
+      BODY_HTML = <<~GRAPHQL.freeze
+        query($id: ID!) {
+          node(id: $id) {
+            ... on Issue { bodyHTML }
+            ... on PullRequest { bodyHTML }
+          }
+        }
+      GRAPHQL
+
+      ALL = { ISSUES:, PULL_REQUESTS:, ISSUE:, PULL_REQUEST:, COMMITS:, BLOB_TEXT:, COMMIT_PULL_REQUESTS:, BODY_HTML: }.freeze
     end
   end
 end

data/lib/shiplog/version.rb

@@ -1,3 +1,3 @@
 module Shiplog
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/shiplog.rb

@@ -12,5 +12,78 @@ module Shiplog
     def config = (@config ||= Configuration.new)
     def configure = yield(config)
     def reset_config! = (@config = nil)
+
+    # The number of approved features and changes approved after `since`, or all of them while it is nil, capped
+    # at 99. Counted on approved_at (when the entry was approved), not released_on (the list's order). The host supplies the timestamp (Shiplog doesn't know its users): see config.on_changelog_seen.
+    def unseen_count(since: nil) = Entry.unseen_count(since:)
+
+    ACTIVE_STORAGE_TABLES = %w[active_storage_attachments active_storage_blobs].freeze
+
+    # Whether the host loaded Active Storage (its engine and the model macros). The declaration on Entry needs
+    # only this, so it never touches the database.
+    def active_storage_loaded? = !!(defined?(ActiveStorage::Engine) && ActiveRecord::Base.respond_to?(:has_many_attached))
+
+    # Whether screenshots can work: Active Storage is loaded and its tables exist (a host that loads
+    # `rails/all` but never ran active_storage:install would otherwise fail on every query). Without either,
+    # every image feature stays off instead of failing.
+    def active_storage? = active_storage_loaded? && active_storage_tables?
+
+    # Whether the Active Storage tables exist. Checked lazily, on first use, then remembered for the life of the
+    # process, so public pages never look at the schema again. When the database can't be reached (at boot, say)
+    # the answer is "not yet known": false for now, and asked again next time. The reason is logged once.
+    def active_storage_tables?
+      return @active_storage_tables unless @active_storage_tables.nil?
+
+      present = ActiveRecord::Base.with_connection { |connection| ACTIVE_STORAGE_TABLES.all? { |table| connection.data_source_exists?(table) } }
+      log_images_off("Active Storage's tables are missing (#{ACTIVE_STORAGE_TABLES.join(", ")}). Run bin/rails active_storage:install and db:migrate to enable them.") unless present || !config.images
+      @active_storage_tables = present
+    rescue ActiveRecord::ActiveRecordError
+      false
+    end
+
+    # Forgets what was learned about the schema and what was logged (tests, and hosts that create the tables at runtime).
+    def reset_images_checks!
+      @active_storage_tables = nil
+      @images_off_logged = nil
+      @image_variants = nil
+    end
+
+    # Logged once at boot (see Shiplog::Engine): screenshots wanted but Active Storage missing. A missing
+    # table is logged by the check itself, the first time it runs.
+    def log_images_status
+      return unless config.images
+
+      if !active_storage_loaded? then log_images_off("Active Storage is not loaded. Require active_storage/engine to enable them.")
+      else active_storage_tables?
+      end
+    end
+
+    # Whether the admin can show thumbnails as variants: the image_processing gem is loaded and so is a
+    # processor for it (ruby-vips, which must load, or mini_magick). Otherwise the originals are shown.
+    def image_variants?
+      return @image_variants unless @image_variants.nil?
+
+      @image_variants = Gem.loaded_specs.key?("image_processing") && (vips_loads? || Gem.loaded_specs.key?("mini_magick"))
+    end
+
+    # Whether screenshots are in use: config.images and Active Storage.
+    def images? = config.images && active_storage?
+
+    private
+
+    def vips_loads?
+      return true if defined?(::Vips)
+
+      Gem.loaded_specs.key?("ruby-vips") && require("vips")
+    rescue LoadError
+      false
+    end
+
+    def log_images_off(reason)
+      @images_off_logged ||= Set.new
+      return unless @images_off_logged.add?(reason)
+
+      Rails.logger&.info("[shiplog] Screenshots are off: #{reason}")
+    end
   end
 end

data/lib/tasks/shiplog.rake

@@ -0,0 +1,29 @@
+# Shiplog::Engine and Shiplog::Admin::Engine share the gem's root, so Rails loads this file once for each: the
+# guard keeps every task from running twice.
+unless Rake::Task.task_defined?("shiplog:backfill_slugs")
+  namespace :shiplog do
+    desc "Give approved changelog entries that have no permalink slug one (entries approved by code older than 0.3.0 after the migration ran)"
+    task backfill_slugs: :environment do
+      count = Shiplog::Entry.backfill_slugs
+      puts "Shiplog: gave #{count} #{count == 1 ? "entry" : "entries"} a slug."
+    end
+
+    desc "Translate approved entries and area names that have no current translation into config.locales (entries approved before 0.3.0 get none). BATCH_SIZE=100"
+    task translate_approved: :environment do
+      if Shiplog.config.locales.empty?
+        puts "Shiplog: config.locales is empty, nothing to translate."
+      elsif Shiplog.config.rewriter.nil?
+        puts "Shiplog: config.rewriter is not set, so nothing can be translated."
+      else
+        result = Shiplog::Entry.enqueue_missing_translations(batch_size: ENV.fetch("BATCH_SIZE", 100).to_i.clamp(1, 10_000))
+        approved = result[:approved]
+        puts "Shiplog: #{approved} approved #{approved == 1 ? "entry" : "entries"}."
+        result[:enqueued].each do |locale, count|
+          puts "Shiplog: #{locale}: #{count} enqueued, #{approved - count} current."
+        end
+        areas = Shiplog::Area.enqueue_missing_translations
+        puts "Shiplog: #{areas} #{areas == 1 ? "area" : "areas"} enqueued for name translation."
+      end
+    end
+  end
+end