conceptql 0.6.0 → 0.7.0

data/lib/conceptql/diagram_renderer/js_format.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module ConceptQL
+  module DiagramRenderer
+    # The JavaScript rules that the ported renderer code depends on: how a value
+    # becomes a string (String(value), template literals, Array#join), which
+    # values are falsy, and the order of Object.entries. The JavaScript renderer
+    # builds path strings and labels with these rules, so the Ruby port must use
+    # them to produce the same strings.
+    module JsFormat
+      module_function
+
+      # Number::toString (ECMAScript 6.1.6.1.20) for a finite or non-finite
+      # number: 100.0 is "100", 1.0e-7 is "1e-7", -0.0 is "0".
+      def number(value)
+        return value.to_s if value.is_a?(Integer)
+
+        value = Float(value)
+        return "NaN" if value.nan?
+        return value.positive? ? "Infinity" : "-Infinity" if value.infinite?
+        return "0" if value.zero?
+        return "-#{number(-value)}" if value.negative?
+
+        digits, n = shortest_digits(value)
+        k = digits.length
+        if k <= n && n <= 21
+          digits + ("0" * (n - k))
+        elsif n.positive? && n <= 21
+          "#{digits[0, n]}.#{digits[n..]}"
+        elsif n > -6 && n <= 0
+          "0.#{'0' * -n}#{digits}"
+        else
+          exponent = n - 1
+          sign = exponent.negative? ? "-" : "+"
+          mantissa = k == 1 ? digits : "#{digits[0]}.#{digits[1..]}"
+          "#{mantissa}e#{sign}#{exponent.abs}"
+        end
+      end
+
+      # String(value) for a JSON value.
+      def string(value)
+        case value
+        when nil then "null"
+        when String then value
+        when Numeric then number(value)
+        when Array then join(value, ",")
+        when Hash then "[object Object]"
+        else value.to_s
+        end
+      end
+
+      # Array.prototype.join: null elements become "".
+      def join(array, separator)
+        array.map { _1.nil? ? "" : string(_1) }.join(separator)
+      end
+
+      # JavaScript truthiness for a JSON value.
+      def truthy?(value)
+        case value
+        when nil, false then false
+        when String then !value.empty?
+        when Float then !(value.zero? || value.nan?)
+        when Integer then !value.zero?
+        else true
+        end
+      end
+
+      # The length of a value as JavaScript reads `value.length`, for the
+      # comparisons in geometry.js: a string's or an array's length, otherwise
+      # NaN (JavaScript's undefined, which compares false with every number).
+      #
+      # A string's length counts characters (code points). JavaScript counts
+      # UTF-16 code units, so a character outside the Basic Multilingual Plane
+      # (an emoji) counts 1 here and 2 in JavaScript.
+      def length(value)
+        value.is_a?(String) || value.is_a?(Array) ? value.length : Float::NAN
+      end
+
+      # Object.entries order for a JSON object: integer-like keys first, in
+      # numeric order, then the other keys in insertion order.
+      def entries(hash)
+        index, other = hash.partition { |key, _| array_index?(key) }
+        index.sort_by { |key, _| key.to_i } + other
+      end
+
+      # String.prototype.trimEnd: the JavaScript WhiteSpace and LineTerminator
+      # characters.
+      TRAILING_WHITESPACE = /[\t\n\v\f\r    - 

  　]+\z/
+
+      def trim_end(text) = text.sub(TRAILING_WHITESPACE, "")
+
+      # The shortest decimal digits that round-trip to `value` (positive,
+      # finite), and the exponent n of ECMAScript's definition: value is
+      # 0.<digits> x 10^n. Ruby's Float#to_s prints the same shortest digits.
+      def shortest_digits(value)
+        mantissa, exponent = value.to_s.split("e")
+        whole, fraction = mantissa.split(".")
+        digits = whole + fraction.to_s
+        n = whole.length + exponent.to_i
+        stripped = digits.sub(/\A0+/, "")
+        n -= digits.length - stripped.length
+        [ stripped.sub(/0+\z/, ""), n ]
+      end
+
+      def array_index?(key)
+        key.is_a?(String) && key.match?(/\A(?:0|[1-9]\d*)\z/) && key.to_i < 4_294_967_295
+      end
+
+      private_class_method :shortest_digits, :array_index?
+    end
+  end
+end

data/lib/conceptql/diagram_renderer/resvg.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+
+module ConceptQL
+  module DiagramRenderer
+    # The resvg command-line program (https://github.com/linebender/resvg), run
+    # as a subprocess: the bounding box of a drawing and PNG output.
+    # mise.toml pins the release (VERSION) and says why it is that release.
+    # resvg is also the engine of the JavaScript static exporter
+    # (@resvg/resvg-js in frontend/lib/conceptql-diagram/cli). Both use the same
+    # fonts: the three Roboto files, no system fonts, default family Roboto
+    # (resvgOptions() in cli/src/render-static.js).
+    #
+    #   resvg = ConceptQL::DiagramRenderer::Resvg.new(fonts_dir: "assets/diagram/fonts")
+    #   resvg.bbox(svg) # => [x, y, width, height]
+    #   resvg.png(svg)  # => PNG bytes
+    class Resvg
+      VERSION = "0.33.0"
+      FONT_FILES = %w[Roboto-400.ttf Roboto-700.ttf Roboto-Italic-400.ttf].freeze
+      DEFAULT_FONT_FAMILY = "Roboto"
+      # The id of the group that bbox wraps around the drawing.
+      BBOX_ID = "conceptql-diagram-bbox"
+      # The root element's start tag. A quoted attribute value may hold ">".
+      ROOT_START = /<svg\b(?:[^>"']|"[^"]*"|'[^']*')*>/
+
+      # A failed run: the program is missing, exits non-zero, or prints no box.
+      class Error < StandardError
+        attr_reader :command, :status, :stderr
+
+        def initialize(command:, status: nil, stderr: "", reason: nil)
+          @command = command
+          @status = status
+          @stderr = stderr
+          exit_text = status ? "exit status #{status}" : "no exit status"
+          super([ "resvg failed: #{reason || exit_text}", "command: #{command.join(' ')}", "stderr: #{stderr}" ].join("\n"))
+        end
+      end
+
+      attr_reader :program, :fonts_dir
+
+      # fonts_dir holds FONT_FILES. program is the resvg executable (a name on
+      # PATH or a path).
+      def initialize(fonts_dir:, program: "resvg")
+        @fonts_dir = fonts_dir.to_s
+        @program = program.to_s
+      end
+
+      # The version that `resvg --version` prints, e.g. "0.33.0".
+      def version
+        run([ "--version" ]).strip
+      end
+
+      # The bounding box of the whole drawing, in user units, as
+      # [x, y, width, height]: what resvg-js getBBox() returns for the same SVG.
+      #
+      # The CLI has no "box of everything" mode. --query-all prints
+      # "id,x,y,width,height" for each element with an id, with text converted
+      # to paths and the stroke included, as getBBox() does. The root has no id,
+      # so bbox wraps the root's content in one group with BBOX_ID and reads
+      # that group's line. In resvg 0.33 the box is in the coordinates of the
+      # root's content, so the viewBox and width/height do not change it.
+      # --query-all rounds to 3 decimal places. An empty drawing has no box and
+      # raises Error.
+      def bbox(svg)
+        start = svg.match(ROOT_START) or raise ArgumentError, "no <svg> start tag in the input"
+        close = svg.rindex("</svg>") or raise ArgumentError, "no </svg> end tag in the input"
+        wrapped = "#{svg[0...start.end(0)]}<g id=\"#{BBOX_ID}\">#{svg[start.end(0)...close]}</g>#{svg[close..]}"
+        with_input(wrapped) do |input|
+          command = [ "--query-all", *font_arguments, input ]
+          line = run(command).lines.find { |l| l.start_with?("#{BBOX_ID},") }
+          raise Error.new(command: full(command), status: 0, reason: "no bounding box for ##{BBOX_ID}; the drawing may be empty") unless line
+
+          line.strip.split(",").drop(1).map { |n| Float(n) }
+        end
+      end
+
+      # The SVG rasterized to PNG bytes, at the size of its width and height.
+      def png(svg)
+        with_input(svg) do |input|
+          output = File.join(File.dirname(input), "out.png")
+          run([ *font_arguments, input, output ])
+          File.binread(output)
+        end
+      end
+
+      private
+
+      def font_arguments
+        FONT_FILES.flat_map { |f| [ "--use-font-file", File.join(fonts_dir, f) ] } +
+          [ "--skip-system-fonts", "--font-family", DEFAULT_FONT_FAMILY ]
+      end
+
+      def full(arguments) = [ program, *arguments ]
+
+      # The SVG goes to the program as a file in a new temporary directory, not
+      # on stdin: with stdin input, resvg prints a warning to stdout, which
+      # would corrupt PNG output on stdout. The directory is also the
+      # program's --resources-dir default, so a relative href finds nothing.
+      def with_input(svg)
+        Dir.mktmpdir("conceptql-diagram-resvg") do |dir|
+          input = File.join(dir, "in.svg")
+          File.write(input, svg)
+          yield input
+        end
+      end
+
+      def run(arguments)
+        command = full(arguments)
+        stdout, stderr, status = Open3.capture3(*command)
+        raise Error.new(command:, status: status.exitstatus, stderr:) unless status.success?
+
+        stdout
+      rescue SystemCallError => e
+        raise Error.new(command:, stderr: "", reason: "cannot run #{program}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/conceptql/diagram_renderer/sprite.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ConceptQL
+  module DiagramRenderer
+    # The operator icon sprite: markup that holds <symbol id="operator-..">
+    # elements, which the drawing's <use> elements refer to. The gem's copy,
+    # assets/diagram/operators.svg, is the content of the hidden
+    # <div class="operators"> of frontend/index.html. The markup may also be a
+    # whole HTML page: only the elements with an id matter.
+    #
+    # The sprite is read with a small tag scanner, not an XML parser (the
+    # library uses the standard library only). It expects well-formed markup
+    # with quoted attribute values, as the sprite is. Each element with an id
+    # keeps its markup exactly as written, for copying into an SVG.
+    class Sprite
+      TAG = %r{
+        <!--.*?-->
+        | <!\[CDATA\[.*?\]\]>
+        | <[!?][^>]*>
+        | </(?<close>[^\s>]+)\s*>
+        | <(?<open>[^\s/>]+)(?<attributes>(?:[^>"']|"[^"]*"|'[^']*')*?)(?<empty>/?)>
+      }mx
+      ATTRIBUTE = /([^\s=]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/
+
+      # One element with an id: where its start tag is, its markup, and the ids
+      # its descendants refer to (Svg.references of each, in document order).
+      Entry = Data.define(:at, :markup, :references)
+
+      def initialize(markup)
+        @entries = {}
+        scan(markup)
+      end
+
+      def key?(id) = @entries.key?(id)
+
+      # The markup of the element with this id.
+      def markup(id) = @entries.fetch(id).markup
+
+      # The ids that the element's descendants refer to.
+      def references(id) = @entries.fetch(id).references
+
+      private
+
+      # As querySelectorAll("[id]") into a Map: when two elements share an id,
+      # the later one (in document order) wins.
+      def scan(markup)
+        open = []
+        tags = []
+        markup.scan(TAG) do
+          match = Regexp.last_match
+          if match[:open]
+            attributes = match[:attributes].scan(ATTRIBUTE).to_h { |name, double, single| [ name, double || single ] }
+            tag = { at: match.begin(0), id: attributes["id"], references: Svg.references(attributes) }
+            tags << tag
+            match[:empty].empty? ? open.push([ match[:open], tag ]) : record(markup, tag, tags, match.end(0))
+          elsif match[:close]
+            index = open.rindex { |name, _| name == match[:close] } or next
+            _, tag = open.slice!(index..).first
+            record(markup, tag, tags, match.end(0))
+          end
+        end
+      end
+
+      def record(markup, tag, tags, finish)
+        return unless tag[:id]
+        return if @entries[tag[:id]] && @entries[tag[:id]].at > tag[:at]
+
+        inner = tags.select { |t| t[:at] > tag[:at] && t[:at] < finish }.flat_map { _1[:references] }
+        @entries[tag[:id]] = Entry.new(at: tag[:at], markup: markup[tag[:at]...finish], references: inner)
+      end
+    end
+  end
+end

data/lib/conceptql/diagram_renderer/static.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ConceptQL
+  module DiagramRenderer
+    # A standalone static SVG of a diagram: renderStatic in
+    # frontend/lib/conceptql-diagram/cli/src/render-static.js. The Drawing,
+    # then makeStandalone (inline the sprite symbols the drawing uses, add the
+    # <style>) and fitToContent (a viewBox around the drawing, measured by
+    # resvg, and a background rect).
+    #
+    #   ConceptQL::DiagramRenderer::Static.new(configuration).render(input) # => SVG text
+    class Static
+      PADDING = 24
+      BACKGROUND = "#f4f2f3"
+      SVG_NS = "http://www.w3.org/2000/svg"
+      XLINK_NS = "http://www.w3.org/1999/xlink"
+      # The canvas that fitToContent measures on: larger than any diagram.
+      MEASURE = [ -5000, -5000, 10_000, 10_000 ].freeze
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def render(input, show_counts: false, show_options: false)
+        drawing = Drawing.new(DiagramData.from(input), show_counts:, show_options:)
+        algorithm = drawing.algorithm
+        style = Svg.element("style", {}, [ @configuration.standalone_style_text ])
+        defs = Svg.element("defs", {}, drawing.gradients + symbols(algorithm))
+
+        x, y, width, height = @configuration.resvg.bbox(root(MEASURE, [ style, defs, algorithm ]).to_s)
+        raise "the diagram rendered nothing measurable" unless width.positive? && height.positive?
+
+        view_box = [ (x - PADDING).floor, (y - PADDING).floor, (width + (2 * PADDING)).ceil, (height + (2 * PADDING)).ceil ]
+        background = Svg.element("rect", { "x" => view_box[0], "y" => view_box[1], "width" => view_box[2], "height" => view_box[3], "fill" => BACKGROUND })
+        root(view_box, [ style, defs, background, algorithm ]).to_s
+      end
+
+      private
+
+      def root(view_box, children)
+        Svg.element("svg", {
+          "xmlns" => SVG_NS,
+          "xmlns:xlink" => XLINK_NS,
+          "class" => "vis is-new",
+          "viewBox" => view_box.join(" "),
+          "width" => view_box[2],
+          "height" => view_box[3]
+        }, children)
+      end
+
+      # The sprite elements the drawing refers to, and those they refer to, in
+      # the order makeStandalone finds them: document order, each one's own
+      # references right after it.
+      def symbols(algorithm)
+        sprite = @configuration.sprite
+        needed = []
+        visit = lambda do |refs|
+          refs.each do |id|
+            next if needed.include?(id) || !sprite.key?(id)
+
+            needed << id
+            visit.call(sprite.references(id))
+          end
+        end
+        visit.call(algorithm.descendants.flat_map { Svg.references(_1.attributes) })
+        needed.map { Svg::Raw.new(sprite.markup(_1)) }
+      end
+    end
+  end
+end

data/lib/conceptql/diagram_renderer/svg.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ConceptQL
+  module DiagramRenderer
+    # SVG markup built with plain strings: an element tree, its serialization
+    # with XML escaping, and the references (#id) that its elements make.
+    #
+    # Attribute values and text are written as the DOM writes the values that
+    # renderer.js sets: a number as JavaScript's Number toString writes it
+    # (JsFormat), and a nil attribute is left out (d3's attr(name, null)
+    # removes the attribute). Every attribute value and text is escaped, because
+    # operator names, values and options come from users.
+    module Svg
+      # An element: a name, attributes in the order they are written, and
+      # children (Element, Raw or String text).
+      Element = Data.define(:name, :attributes, :children) do
+        def initialize(name:, attributes: {}, children: [])
+          super(name:, attributes: attributes.reject { |_, value| value.nil? }.transform_values { JsFormat.string(_1) }, children:)
+        end
+
+        def to_s
+          attrs = attributes.map { |key, value| %( #{key}="#{Svg.escape_attribute(value)}") }.join
+          return "<#{name}#{attrs}/>" if children.empty?
+
+          "<#{name}#{attrs}>#{children.map { _1.is_a?(String) ? Svg.escape_text(_1) : _1.to_s }.join}</#{name}>"
+        end
+
+        # The element's descendants in document order (querySelectorAll("*")),
+        # without the element itself.
+        def descendants
+          children.grep(Element).flat_map { [ _1, *_1.descendants ] }
+        end
+      end
+
+      # Markup copied as it is, such as an icon <symbol> from the sprite.
+      Raw = Data.define(:markup) do
+        def to_s = markup
+      end
+
+      # The attributes that makeStandalone (cli/src/render-static.js) reads a
+      # url(#id) reference from, in the order it reads them.
+      URL_ATTRIBUTES = %w[fill stroke filter clip-path mask].freeze
+      URL_REFERENCE = /url\(#([^)]+)\)/
+
+      module_function
+
+      def element(name, attributes = {}, children = []) = Element.new(name:, attributes:, children:)
+
+      # The ids that one element's attributes refer to, in the order
+      # makeStandalone finds them: the href (xlink:href, else href), then a
+      # url(#id) in each of URL_ATTRIBUTES. attributes is a hash of qualified
+      # names to values.
+      def references(attributes)
+        href = [ attributes["xlink:href"], attributes["href"] ].find { _1 && !_1.empty? }
+        refs = href&.start_with?("#") ? [ href[1..] ] : []
+        refs + URL_ATTRIBUTES.filter_map { attributes[_1]&.match(URL_REFERENCE)&.[](1) }
+      end
+
+      # An attribute value as XMLSerializer escapes it. The tab, newline and
+      # carriage return are character references, so a parser reads them back
+      # unchanged (it would read a raw one as a space).
+      def escape_attribute(value)
+        value.gsub(/[&<>"\t\n\r]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;", "\t" => "&#x9;", "\n" => "&#xA;", "\r" => "&#xD;")
+      end
+
+      # Text as XMLSerializer escapes it. A carriage return is a character
+      # reference, so a parser does not turn it into a newline.
+      def escape_text(text)
+        text.gsub(/[&<>\r]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", "\r" => "&#xD;")
+      end
+    end
+  end
+end