archsight 0.4.2 → 0.5.0

data/lib/archsight/helpers/diagram_includes.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../assets"
+
+module Archsight
+  module Helpers
+    # Loads the diagrams that `include "<path>"` names (see Archsight::Diagram::Includes):
+    #
+    #   archsight://Kind/name    the `architecture/diagram` of that resource
+    #   file://path/to/x.asd     an .asd file, relative to the resources directory (never outside it)
+    #
+    # #call returns the diagram source, or `:missing` / `:forbidden` / `:invalid`. Without a database only
+    # `file://` paths work (the standalone `archsight diagram`).
+    class DiagramIncludes
+      ARCHSIGHT = "archsight://"
+      FILE = "file://"
+      ANNOTATION = "architecture/diagram"
+      MAX_BYTES = 1_000_000
+
+      # The loader for a database, whose path is the resources directory
+      def self.for(database)
+        new(database, resources_dir: (database.path if database.respond_to?(:path)))
+      end
+
+      def initialize(database, resources_dir:)
+        @database = database
+        @resources_dir = resources_dir
+      end
+
+      def call(path)
+        if path.start_with?(ARCHSIGHT)
+          resource(path.delete_prefix(ARCHSIGHT))
+        elsif path.start_with?(FILE)
+          file(path.delete_prefix(FILE))
+        else
+          :invalid
+        end
+      end
+
+      private
+
+      # `Kind/name`; names contain `:` but a kind never contains `/`, so the first `/` separates them
+      def resource(reference)
+        return :forbidden unless @database
+
+        kind, name = reference.split("/", 2)
+        return :invalid if kind.to_s.empty? || name.to_s.empty? || !Archsight::Resources[kind]
+
+        source = @database.instance_by_kind(kind, name)&.annotations&.fetch(ANNOTATION, nil)
+        source.is_a?(String) && !source.strip.empty? ? source : :missing
+      end
+
+      def file(path)
+        return :invalid if @resources_dir.nil? || !Archsight::Assets.asd?(path)
+        return :forbidden if path.start_with?("/") # file:///etc/x.asd; relative to the resources directory only
+
+        real = Archsight::Assets.file_for(path, resources_dir: @resources_dir)
+        return :missing unless real
+        return :forbidden if File.size(real) > MAX_BYTES
+
+        File.read(real, encoding: "UTF-8")
+      rescue SystemCallError
+        :missing
+      end
+    end
+  end
+end

data/lib/archsight/helpers.rb

@@ -7,6 +7,7 @@ require_relative "helpers/fenced_blocks"
 require_relative "helpers/view_blocks"
 require_relative "helpers/requirements_blocks"
 require_relative "helpers/resource_resolver"
+require_relative "helpers/diagram_includes"
 require_relative "helpers/embeds"
 require_relative "helpers/wiki_links"
 require_relative "helpers/asset_images"

data/lib/archsight/linter.rb

@@ -24,6 +24,7 @@ module Archsight
     def initialize(database)
       @database = database
       @errors = []
+      @diagram_warnings = []
     end
 
     def validate
@@ -47,7 +48,7 @@ module Archsight
     # annotations their kind marks `deprecated:`. They are not errors, so they do not make `archsight lint` fail.
     def warnings
       renamed = @database.respond_to?(:deprecations) ? @database.deprecations.map(&:to_s) : []
-      renamed + deprecated_annotations
+      renamed + deprecated_annotations + @diagram_warnings
     end
 
     # Structural modeling checks (rules of "Choosing the Kind", see Linter::Structure). Warnings, never errors.
@@ -402,7 +403,10 @@ module Archsight
     # Renders with the same resolver the web UI uses, so a `resource` reference that would show as a broken link there is reported here
     def render_diagram_source(instance, where, source)
       unresolved = []
-      Archsight::Diagram.render(source, resolver: Helpers::ResourceResolver.new(@database), unresolved: unresolved)
+      warnings = []
+      Archsight::Diagram.render(source, resolver: Helpers::ResourceResolver.new(@database), unresolved: unresolved,
+                                        includes: diagram_includes, warnings: warnings)
+      warnings.each { |message| @diagram_warnings << "#{instance.path_ref}: Diagram in #{where}: #{message}" }
       unresolved.each do |u|
         @errors << "#{instance.path_ref}: Diagram resource link #{u[:reference].inspect} #{u[:reason]} in #{where} (node #{u[:node].inspect}, line #{u[:line]})"
       end
@@ -410,6 +414,10 @@ module Archsight
       @errors << "#{instance.path_ref}: Diagram error in #{where}: #{e.message}"
     end
 
+    def diagram_includes
+      @diagram_includes ||= Helpers::DiagramIncludes.for(@database)
+    end
+
     def validate_view_fields(instance)
       check_view_components(instance, instance.annotations["view/fields"].to_s.split(",").map(&:strip))
     end

data/lib/archsight/markdown.rb

@@ -14,9 +14,25 @@ module Archsight
     # Raw HTML whose text is kept as it is
     VERBATIM = %w[pre code script style textarea].freeze
 
+    # Fenced code and inline code, which are left as written
+    CODE = /(^[ \t]*(?:`{3,}|~{3,}).*?^[ \t]*(?:`{3,}|~{3,})[ \t]*$|`+[^`\n].*?`+)/m
+    WIKI_LINK_PIPE = /\[\[[^\]\n]*\]\]/
+
     def self.document(text, **)
-      Kramdown::Document.new(text.to_s, **OPTIONS, **)
+      Kramdown::Document.new(protect_wiki_link_pipes(text.to_s), **OPTIONS, **)
+    end
+
+    # Kramdown reads every line with a `|` as a table row, which would cut `[[Target|label]]` in two (a list item
+    # "Related: [[A/B|b]], [[C/D|d]]" became one table row). An escaped pipe is a plain `|` again in the HTML,
+    # which is what WikiLinks expects; code is untouched, it would show the backslash.
+    def self.protect_wiki_link_pipes(text)
+      return text unless text.include?("[[") && text.include?("|")
+
+      text.split(CODE).each_with_index.map do |part, index|
+        index.odd? ? part : part.gsub(WIKI_LINK_PIPE) { |link| link.gsub(/(?<!\\)\|/, "\\\\|") }
+      end.join
     end
+    private_class_method :protect_wiki_link_pipes
 
     # The document without the newlines of the source in its text, for a target that keeps a newline instead of
     # reading it as a space (Confluence): a soft line break becomes a space, the newline after a line break goes.

data/lib/archsight/pdf/cache.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Archsight
+  module Pdf
+    # The last PDFs that were made, by fingerprint of what they were made from, and a limit on how many are made at
+    # the same time (typst needs a CPU for seconds, a page nobody changed needs none).
+    class Cache
+      def initialize(entries: 16, parallel: 2)
+        @entries = entries
+        @store = {}
+        @lock = Mutex.new
+        @slots = SizedQueue.new(parallel)
+        parallel.times { @slots << true }
+      end
+
+      # @param key [String] fingerprint
+      # @yield makes the PDF when it is not cached
+      # @return [String]
+      def fetch(key, &)
+        cached = @lock.synchronize { @store.delete(key)&.tap { |pdf| @store[key] = pdf } }
+        return cached if cached
+
+        pdf = make(&)
+        @lock.synchronize do
+          @store[key] = pdf
+          @store.shift while @store.size > @entries
+        end
+        pdf
+      end
+
+      private
+
+      def make
+        @slots.pop
+        yield
+      ensure
+        @slots << true
+      end
+    end
+  end
+end

data/lib/archsight/pdf/compiler.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+require_relative "../user_config"
+
+module Archsight
+  module Pdf
+    # Raised when a document cannot be turned into a PDF; the message is safe to show
+    class Error < StandardError; end
+
+    # Raised when typst is not installed
+    class Unavailable < Error; end
+
+    # Runs the `typst` command line tool on a prepared directory. The binary is `pdf.typst` of the user
+    # configuration (`ARCHSIGHT_PDF_TYPST`), else `typst` from the PATH.
+    class Compiler
+      DEFAULT_TIMEOUT = 60
+      ERROR_LINES = 12
+
+      def initialize(binary: nil, timeout: nil)
+        @binary = binary || UserConfig.setting("pdf", "typst") || "typst"
+        @timeout = (timeout || UserConfig.setting("pdf", "timeout") || DEFAULT_TIMEOUT).to_i
+      end
+
+      # @param dir [String] directory with main.typ; it is the Typst root, nothing outside of it can be read
+      # @param font_paths [Array<String>] directories with additional fonts
+      # @return [String] the PDF
+      # @raise [Unavailable] without typst
+      # @raise [Error] if typst fails or runs too long
+      def compile(dir, font_paths: [])
+        output = File.join(dir, "out.pdf")
+        args = [@binary, "compile", "--root", dir, *font_paths.flat_map { |p| ["--font-path", p] }, File.join(dir, "main.typ"), output]
+        _out, err, status = run(args, dir)
+        raise Error, "typst failed:\n#{err.lines.first(ERROR_LINES).join}" unless status.success? && File.file?(output)
+
+        File.binread(output)
+      end
+
+      # Whether PDF files can be placed as images (typst 0.14 and newer)
+      def pdf_images?
+        return @pdf_images if defined?(@pdf_images)
+
+        out, status = Open3.capture2(@binary, "--version")
+        version = out[/(\d+)\.(\d+)/]
+        @pdf_images = status.success? && !version.nil? && (Gem::Version.new(version) >= Gem::Version.new("0.14"))
+      rescue Errno::ENOENT
+        raise Unavailable, "typst is not installed (set ARCHSIGHT_PDF_TYPST to its path)"
+      end
+
+      private
+
+      def run(args, dir)
+        Open3.popen3(*args, chdir: dir) do |stdin, stdout, stderr, thread|
+          stdin.close
+          out = Thread.new { stdout.read }
+          err = Thread.new { stderr.read }
+          unless thread.join(@timeout)
+            Process.kill("KILL", thread.pid)
+            raise Error, "typst took longer than #{@timeout} seconds"
+          end
+          [out.value, err.value, thread.value]
+        end
+      rescue Errno::ENOENT
+        raise Unavailable, "typst is not installed (set ARCHSIGHT_PDF_TYPST to its path)"
+      end
+    end
+  end
+end

data/lib/archsight/pdf/dependency_graph.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "open3"
+require "digest"
+require_relative "../renderer"
+require_relative "../graph"
+require_relative "../user_config"
+require_relative "../resources"
+
+module Archsight
+  module Pdf
+    # The dependency graph of a resource as an SVG document, the picture the resource's page shows: the resources its
+    # relations lead to, as far as the page opens it (two steps, the layer of the resource and the one below it). The
+    # page draws it in the browser; here it is drawn by the `dot` command of Graphviz (`pdf.dot` /
+    # `ARCHSIGHT_PDF_DOT`, else `dot` from the PATH). A resource without relations has no graph, and without `dot`
+    # there is none either, which is not an error: the document is made without it.
+    class DependencyGraph
+      include Archsight::GraphvisRenderer
+
+      DEPTH = 2
+      BOX = [500.0, 480.0].freeze # points: the text width of a page and the height a graph may take (to choose the direction)
+      DIRECTIONS = %w[LR TB].freeze # left to right as on the page, or top to bottom
+      TIMEOUT = 30
+      CACHE_ENTRIES = 32
+
+      # The colours of the layers (the page colours its nodes with the same, by CSS)
+      LAYER_COLOURS = {
+        "strategy" => "#F4A261", "business" => "#F9DC5C", "application" => "#6CBEED", "technology" => "#8AC926",
+        "implementation" => "#F48FB1", "motivation" => "#CE93D8", "other" => "#cccccc"
+      }.freeze
+      # For the SVG, where the colours come as CSS: the page's style, without the borders of the label tables
+      STYLE = "<style>\n#{LAYER_COLOURS.map { |layer, hex| ".layer-#{layer} path[fill=\"lightgrey\"] { fill: #{hex}; stroke: #{hex}; }" }.join("\n")}\n" \
+              ".node polygon[fill=\"none\"] { stroke: none; }\n.node text { fill: #000000; }\n</style>\n".freeze
+      LAYER_CLASS = /("class" = "[^"]*\blayer-(\w+)[^"]*")/
+
+      @cache = {}
+      @lock = Mutex.new
+
+      class << self
+        # Colours the nodes by layer, as the page does (the DOT has no colours, they come from the page's CSS)
+        # @return [String] the SVG with a style element after its opening tag
+        def colour_layers(svg)
+          svg.sub(/(<svg\b[^>]*>)/) { "#{Regexp.last_match(1)}\n#{STYLE}" }
+        end
+
+        # The DOT of the page with what the page's CSS adds: the fill of a node by its layer, and label tables without borders
+        def paint(dot)
+          dot.gsub(LAYER_CLASS) do
+            hex = LAYER_COLOURS.fetch(Regexp.last_match(2), LAYER_COLOURS["other"])
+            "#{Regexp.last_match(1)} \"fillcolor\" = \"#{hex}\" \"color\" = \"#{hex}\""
+          end.gsub("<TABLE>", '<TABLE BORDER="0" CELLBORDER="0" CELLSPACING="0">')
+        end
+
+        def cached(key)
+          @lock.synchronize { @cache[key] } || yield.tap do |value|
+            @lock.synchronize do
+              @cache[key] = value
+              @cache.shift while @cache.size > CACHE_ENTRIES
+            end
+          end
+        end
+      end
+
+      # @param layers [Array<String>, nil] the layers to follow; the page's default for the resource's layer if nil
+      def initialize(database, resource, depth: DEPTH, layers: nil, binary: nil)
+        @database = database
+        @resource = resource
+        @depth = depth
+        @layers = layers || Archsight::GraphvisRenderer.default_graph_layers(resource.class.layer)
+        @binary = binary || UserConfig.setting("pdf", "dot") || "dot"
+      end
+
+      # @return [Boolean] whether the graph would show more than the resource itself
+      def relations?
+        !graph_targets(@resource, @layers).empty?
+      end
+
+      # @return [String, nil] the graph as a PDF page (drawn by `dot` itself, with the fonts it measured the text with), nil
+      #   if there is nothing to draw or `dot` is not installed or fails
+      def pdf = draw("pdf")
+
+      # @return [String, nil] the graph as SVG, coloured by CSS; nil as for #pdf
+      def svg
+        out = draw("svg")
+        out && self.class.colour_layers(out.dup.force_encoding(Encoding::UTF_8))
+      end
+
+      private
+
+      def draw(format)
+        return nil unless relations?
+
+        dot = self.class.paint(create_graph_one(@database, @resource.klass, @resource.name, max_depth: @depth, layers: @layers))
+        self.class.cached(Digest::SHA256.hexdigest("#{@binary}\0#{format}\0#{dot}")) { run(format, oriented(dot)) }
+      end
+
+      # The direction in which the graph is largest on the page: wide graphs read best left to right, tall ones top to
+      # bottom. Left to right (the page's) wins unless the other is clearly better.
+      def oriented(dot)
+        DIRECTIONS.each_with_index.map { |direction, index| [with_direction(dot, direction), index.zero? ? 1.05 : 1.0] }
+                                  .max_by { |candidate, bonus| fit(candidate) * bonus }.first
+      end
+
+      def with_direction(dot, direction)
+        dot.sub(/"rankdir" = "?\w+"?/, "\"rankdir\" = \"#{direction}\"")
+      end
+
+      # How much of its natural size the graph keeps when it is made to fit the box (1.0: nothing lost); 0 if `dot` fails
+      def fit(dot)
+        out, status = Open3.capture2(@binary, "-Tplain", stdin_data: dot)
+        return 0 unless status.success?
+
+        _graph, _scale, width, height = out.lines.first.split
+        [BOX[0] / (width.to_f * 72), BOX[1] / (height.to_f * 72), 1.0].min
+      rescue Errno::ENOENT
+        0
+      end
+
+      def run(format, dot)
+        out, status = Open3.capture2(@binary, "-T#{format}", stdin_data: dot, binmode: true)
+        status.success? && !out.empty? ? out : nil
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/archsight/pdf/document.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "date"
+require "digest"
+require_relative "typst"
+require_relative "markdown"
+require_relative "theme"
+require_relative "images"
+require_relative "embeds"
+require_relative "resource_sheet"
+require_relative "dependency_graph"
+require_relative "../helpers/resource_resolver"
+require_relative "../helpers/diagram_includes"
+require_relative "../helpers/wiki_links"
+
+module Archsight
+  module Pdf
+    # One resource or page as the files typst needs: `main.typ` (the document), the layout library, the theme
+    # and the images. Pages are exported as written; any other resource becomes a generated document (description,
+    # properties, relations, diagram).
+    #
+    # Tags steer the export (page `page/tags`, resource `architecture/tags`):
+    #
+    #   pdf:cover               cover page instead of a title block
+    #   pdf:toc                 table of contents
+    #   pdf:landscape           landscape pages
+    #   pdf:draft               "draft" watermark
+    #   pdf:no-graph            leave the dependency graph out of a resource document
+    #   pdf:template:<name>     pdf Config to use instead of `default`
+    #   version:<x>             document version (else the page property Version, else 1)
+    class Document
+      GRAPH_HEIGHT = 0.8 # share of the page height the dependency graph may take
+      LIBRARY = File.join(__dir__, "typst", "archsight.typ")
+
+      # @return [String] title of the document
+      attr_reader :title
+
+      # @param template [String, nil] name of a pdf Config, overrides the tag
+      # @param draft [Boolean] force the watermark
+      def initialize(database, resource, template: nil, draft: false, resources_dir: Archsight.resources_dir, pdf_images: true)
+        @database = database
+        @resource = resource
+        @resources_dir = resources_dir
+        @pdf_images = pdf_images
+        @tags = tag_list
+        @theme = theme_for(template)
+        @draft = draft || @tags.include?("pdf:draft")
+        @title = title_for
+      end
+
+      # @return [Hash{String => String}] file name => content of everything typst needs, `main.typ` among them
+      def files
+        @files ||= build
+      end
+
+      # @return [Array<String>] directories with fonts to hand to typst
+      def font_paths
+        [@theme.font_dir].compact
+      end
+
+      # A name for the downloaded file
+      def filename
+        "#{@resource.name.to_s.gsub(/[^A-Za-z0-9._-]+/, "-").gsub(/\A[-.]+|-+\z/, "")}.pdf"
+      end
+
+      # Changes whenever the PDF would: the files and the fonts
+      def fingerprint
+        digest = Digest::SHA256.new
+        files.sort.each { |name, content| digest << name << "\0" << content.b << "\0" }
+        font_paths.each { |dir| Dir.children(dir).sort.each { |f| digest << f << File.size(File.join(dir, f)).to_s } }
+        digest.hexdigest[0, 16]
+      end
+
+      private
+
+      # The look, the title and the body are what a variant (see SampleDocument) replaces
+      def theme_for(template)
+        Theme.for(@database, template || tag_value("pdf:template"))
+      end
+
+      def title_for
+        page? ? @resource.title : @resource.name
+      end
+
+      def body(images)
+        page? ? page_body(images) : resource_body(images)
+      end
+
+      def page?
+        @resource.klass == "Page"
+      end
+
+      def build
+        images = Images.new(base_dir: base_dir, resources_dir: @resources_dir, resolver: resolver,
+                            includes: Helpers::DiagramIncludes.for(@database), pdf_images: @pdf_images)
+        body = body(images)
+        files = { "archsight.typ" => File.read(LIBRARY), "main.typ" => main(body) }.merge(images.files)
+        files.merge(logo_files).tap { |f| f["theme.typ"] = @theme.to_typst(**logo_names) }
+      end
+
+      def main(body)
+        meta = "title: #{Typst.lit(@title)}, doc-id: #{opt(doc_id)}, version: #{opt(version)}, date: #{opt(date)}, owner: #{opt(owner)}"
+        args = "theme: theme, #{meta}"
+        front = if @tags.include?("pdf:cover")
+                  "#cover-page(#{args}, kind: #{opt(kind)}, classification: #{opt(classification)})"
+                else
+                  "#title-block(theme: theme, title: #{Typst.lit(@title)}, kind: #{opt(kind)})"
+                end
+        front += "\n#toc-page(theme: theme)" if @tags.include?("pdf:toc")
+        <<~TYPST
+          #import "archsight.typ": *
+          #import "theme.typ": theme
+          #show: doc.with(#{args}, classification: #{opt(classification)}, draft: #{@draft}, landscape: #{@tags.include?("pdf:landscape")})
+          #{front}
+
+          #{body}
+        TYPST
+      end
+
+      # ---- body
+
+      def page_body(images)
+        markdown(images).render(strip_title(@resource.annotations["page/content"].to_s))
+      end
+
+      def resource_body(images)
+        ann = @resource.annotations
+        sheet = ResourceSheet.new(@resource, markdown: ->(text) { markdown(images, offset: 2).render(text) })
+        parts = []
+        # the pictures come first, right after the title, then the text and the facts
+        parts.concat(dependency_graph(images))
+        parts << images.diagram(ann["architecture/diagram"]).to_s if ann["architecture/diagram"].to_s.strip != ""
+        parts << markdown(images, offset: 1).render(ann["architecture/description"]) if ann["architecture/description"].to_s.strip != ""
+        parts.concat(sheet.properties)
+        parts.concat(sheet.relations)
+        parts.join("\n\n")
+      end
+
+      # The dependency graph the resource's page shows, unless the tag `pdf:no-graph` leaves it out
+      def dependency_graph(images)
+        return [] if @tags.include?("pdf:no-graph")
+
+        graph = DependencyGraph.new(@database, @resource)
+        picture = (images.pdf(graph.pdf, max_height: GRAPH_HEIGHT) if @pdf_images && graph.pdf) ||
+                  (images.vector(graph.svg, max_height: GRAPH_HEIGHT) if graph.svg)
+        picture ? [picture] : []
+      end
+
+      # @param embeds [Boolean] whether views, analyses and `![[..]]` embeds are part of the text; the content of an embed
+      #   is rendered without (one level, so embeds cannot include each other)
+      def markdown(images, offset: 0, embeds: true)
+        links = Helpers::WikiLinks.new(@database, resolver: resolver)
+        Markdown.new(heading_offset: offset, image: images.method(:image), diagram: images.method(:diagram), label: links.method(:label_for),
+                     embeds: embeds ? embeds_for(images) : nil)
+      end
+
+      def embeds_for(images)
+        @embeds_for ||= Embeds.new(@database, markdown: ->(inline, text) { markdown(images, offset: 1, embeds: false).render(text, inline: inline) })
+      end
+
+      # The header already shows the title, so a leading "# Title" that repeats it is dropped
+      def strip_title(body)
+        first, rest = body.lstrip.split("\n", 2)
+        heading = first.to_s[/\A#\s+(.+?)\s*#*\s*\z/, 1]
+        heading && [@title, @resource.name].any? { |t| t.to_s.casecmp?(heading) } ? rest.to_s.lstrip : body
+      end
+
+      # ---- metadata
+
+      def properties_hash
+        @properties_hash ||= page? ? @resource.properties.to_h : {}
+      end
+
+      def tag_list
+        raw = @resource.annotations["page/tags"] || @resource.annotations["architecture/tags"]
+        raw.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      # `prefix:value` of a tag
+      def tag_value(prefix)
+        @tags.filter_map { |t| t.delete_prefix("#{prefix}:") if t.start_with?("#{prefix}:") }.first
+      end
+
+      def doc_id = properties_hash["Document ID"] || "#{@resource.klass}/#{@resource.name}"
+      def version = tag_value("version") || properties_hash["Version"] || "1"
+      def classification = properties_hash["Classification"] || @theme.classification
+      def kind = page? ? nil : @resource.klass
+
+      def date
+        (@resource.annotations["page/updated"] || Date.today.iso8601).to_s[0, 10]
+      end
+
+      def owner
+        value = @resource.annotations["page/owner"] || @resource.annotations["page/author"] ||
+                @resource.annotations["architecture/owner"]
+        Annotations::EmailRecipient.parse(value)&.fetch(:name)
+      end
+
+      def base_dir
+        Assets.base_dir_for(@resource, resources_dir: @resources_dir)
+      end
+
+      def resolver
+        @resolver ||= Helpers::ResourceResolver.new(@database)
+      end
+
+      def opt(value)
+        value.to_s.strip.empty? ? "none" : Typst.lit(value)
+      end
+
+      # Logos are staged under fixed names; the file type decides the extension
+      def logo_names
+        { logo: staged_name("logo", @theme.logo), logo_light: staged_name("logo-light", @theme.logo_light) }
+      end
+
+      def logo_files
+        { logo_names[:logo] => @theme.logo, logo_names[:logo_light] => @theme.logo_light }
+          .reject { |name, file| name.nil? || file.nil? }
+          .transform_values { |file| File.binread(file) }
+      end
+
+      def staged_name(base, file)
+        file && "#{base}#{File.extname(file).downcase}"
+      end
+    end
+  end
+end