etassia 0.1.0

data/lib/etassia/parser/builders/kanban.rb

@@ -0,0 +1,411 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+require_relative "../metadata_yaml"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for Kanban diagrams
+      class Kanban < Parslet::Transform
+        # Helper class to build kanban board from indented lines
+        class BoardBuilder
+          attr_reader :columns
+
+          def initialize
+            @columns = []
+            @current_column = nil
+            @items = []
+            @anonymous_index = 0
+          end
+
+          def add_line(line_data)
+            return apply_modifier_line(line_data) if modifier?(line_data)
+
+            @items << item_from(line_data)
+          end
+
+          def modifier?(line_data)
+            line_data[:icon] || line_data[:classes]
+          end
+
+          def apply_modifier_line(line_data)
+            if line_data[:icon]
+              return apply_modifier(:icon, line_data[:icon].to_s)
+            end
+
+            classes = line_data[:classes].to_s.strip.split(/\s+/)
+            apply_modifier(:classes, classes)
+          end
+
+          # An item with no bracket label displays its id. Metadata is parsed
+          # here so both add_card and add_column see it. An absent label is
+          # nil, so `|| id` safely falls back without hiding an empty string.
+          def item_from(line_data)
+            id = resolve_id(line_data[:id])
+            {
+              id: id,
+              text: line_data[:text]&.to_s || id,
+              indent: get_indent_size(line_data[:indent]),
+              metadata: parse_metadata(line_data[:metadata]),
+            }
+          end
+
+          def finalize
+            return if @items.empty?
+
+            # The first item's indent is the column level, as in mermaid's
+            # getSection. An item at that indent is a column; any other
+            # indent is a card of the latest column, including one LESS
+            # indented than the first. Mermaid rejects a less-indented item
+            # only once another item follows it.
+            build_columns(@items.first[:indent])
+          end
+
+          private
+
+          def build_columns(column_indent)
+            shallower = nil
+            @items.each do |item|
+              refuse_item_after(shallower) if shallower
+              shallower = item if item[:indent] < column_indent
+              item[:indent] == column_indent ? add_column(item) : add_card(item)
+            end
+          end
+
+          def refuse_item_after(item)
+            raise Parser::ParseError,
+                  "Items without section detected, " \
+                  "found section (\"#{column_title(item)}\")."
+          end
+
+          # A shape with no id (`(text)`) never captures `:id`. Mermaid
+          # still draws it - it auto-assigns one - so this does too,
+          # deterministically: parsing the same source twice must produce
+          # the same diagram, and a random id would break that on every
+          # call (see the `kanban-1` / `kanban-2` assertions in
+          # spec/etassia/parser/kanban_spec.rb). Unlike
+          # Builders::Block.anonymous_id, this id is never displayed -
+          # `unlabelled_shaped_item` always captures its own `:text`, so
+          # `resolve_id`'s output never reaches TextMeasurement and its
+          # length has no effect on layout (measured: extending it by
+          # 1,000 characters left the rendered SVG byte-identical). The
+          # hyphen keeps generated ids out of the author's namespace,
+          # since identifier_char is `[a-zA-Z0-9_]` and can never spell
+          # one.
+          def resolve_id(id_slice)
+            return id_slice.to_s if id_slice
+
+            @anonymous_index += 1
+            "kanban-#{@anonymous_index}"
+          end
+
+          def add_column(item)
+            column = {
+              id: item[:id],
+              title: column_title(item),
+              icon: item[:metadata][:icon],
+              classes: normalize_classes(item[:metadata][:classes]),
+              cards: [],
+            }
+
+            @columns << column
+            @current_column = column
+          end
+
+          # `::icon(...)`/`:::` lines modify whichever item was added last;
+          # raise rather than silently drop when there is none, matching
+          # mmdc 11.12.0 (which rejects that shape). Both keys are
+          # last-write-wins, matching mermaid's `decorateNode`, which
+          # plainly assigns `node.cssClasses = ...` rather than merging.
+          def apply_modifier(key, value)
+            unless @items.last
+              marker = key == :icon ? "::icon" : ":::"
+              raise Parser::ParseError, "#{marker} with no preceding item."
+            end
+
+            @items.last[:metadata][key] = value
+          end
+
+          # `classes` arrives here as an Array from a `:::a b` directive line
+          # (parse_metadata drops a scalar `classes:` key from `@{ ... }`
+          # metadata entirely - mermaid does not read one). `else` also covers a
+          # nil/absent value, normalized to an empty Array. The single point
+          # both add_column and add_card read from.
+          def normalize_classes(value)
+            case value
+            when Array then value
+            else value.to_s.strip.split(/\s+/)
+            end
+          end
+
+          # The card's own `id` and `text` beat a metadata entry of the same
+          # name, because mermaid ignores `@{ id: ... }` and `@{ text: ... }`.
+          # Merging the metadata FIRST makes that true by construction, with
+          # no exclusion list to keep in step as fields are added.
+          #
+          # A `label:` on a card is kept as its own attribute and drawn as a
+          # separate "Label:" row. That diverges from mermaid, which renders
+          # the label as the card's primary text and draws no such row. The
+          # divergence is pre-existing; correcting it belongs to the
+          # card-conformance bucket.
+          def add_card(item)
+            @current_column[:cards] << item[:metadata].merge(
+              id: item[:id],
+              text: item[:text],
+              classes: normalize_classes(item[:metadata][:classes]),
+            )
+          end
+
+          # A `label:` replaces a COLUMN's display text, which is what mermaid
+          # renders. A label mermaid would treat as unset is already gone by
+          # here - parse_metadata drops it - so falling back to the bracket
+          # text, or to the id, is a plain `||`.
+          def column_title(item)
+            item[:metadata][:label] || item[:text]
+          end
+
+          # `Kanban.metadata_fields` does the real work - a real YAML engine
+          # for structure and resolution - so this is left only to route each
+          # resolved key to the card/column field mermaid's `addNode` reads
+          # it into.
+          # Mermaid reads no `classes` key from metadata; only a `:::`
+          # modifier may set it. Every other resolved key is stored as-is.
+          def parse_metadata(metadata_data)
+            return {} if metadata_data.nil?
+
+            fields = Kanban.metadata_fields(metadata_data)
+            fields.each_with_object({}) do |(key, value), result|
+              next if key == "classes"
+
+              result[key.to_sym] = value
+            end
+          end
+
+          # The grammar captures the indent as a string, "" when absent.
+          def get_indent_size(indent_data)
+            indent_data.to_s.length
+          end
+        end
+
+        # The `@{ ... }` body, resolved by a real YAML engine
+        # (`MetadataYaml`) the way mermaid's js-yaml does: flow vs block is
+        # decided by whether the body contains a newline anywhere. Do not
+        # re-add hand-written grammar rules for YAML legality - duplicate
+        # keys and tab indentation are refused by the engine.
+        #
+        # @raise [Parser::ParseError] on YAML mermaid would also refuse
+        def self.metadata_fields(metadata_data)
+          document, unshield = shield_foreign_breaks(
+            metadata_document(metadata_data),
+          )
+          resolved = MetadataYaml.value(document)
+          raise Parser::ParseError, "Empty metadata." if resolved.nil?
+          return {} unless resolved.is_a?(Hash)
+
+          stored_fields(resolved)
+            .to_h { |key, text| [unshield.call(key), unshield.call(text)] }
+        end
+
+        # Mermaid's own wrapping: a single-line body becomes a flow
+        # mapping between braces, a multiline one is used as written -
+        # see Builders::Flowchart#metadata_document, the same rule.
+        def self.metadata_document(metadata_data)
+          text = metadata_body_text(metadata_data)
+          body = break_quoted_newlines(strip_metadata_comments(text))
+          body.include?("\n") ? "#{body}\n" : "{\n#{body}\n}"
+        end
+        private_class_method :metadata_document
+
+        # NEL, LS and PS are line breaks to Psych but ordinary characters
+        # to js-yaml, and `MetadataYaml` refuses them rather than read them
+        # the wrong way. Mermaid keeps them as text, so they are swapped for
+        # unused private-use characters while the engine reads the body, and
+        # swapped back in the stored fields.
+        #
+        # @return [Array(String, #call)] the shielded body and the function
+        #   that restores a stored string
+        def self.shield_foreign_breaks(document)
+          present = FOREIGN_BREAKS.select { |char| document.include?(char) }
+          return [document, :itself.to_proc] if present.empty?
+
+          shields = present.zip(spare_characters(document, present.size)).to_h
+          [document.gsub(Regexp.union(present), shields), unshielder(shields)]
+        end
+        private_class_method :shield_foreign_breaks
+
+        def self.unshielder(shields)
+          restore = shields.invert
+          pattern = Regexp.union(restore.keys)
+          ->(text) { text.gsub(pattern, restore) }
+        end
+        private_class_method :unshielder
+
+        # A character is spare when the body neither contains it nor spells
+        # it as a `\xHH`, `\uHHHH` or `\UHHHHHHHH` escape - an escape
+        # would otherwise resolve to it and be swapped back by mistake.
+        def self.spare_characters(document, count)
+          taken = taken_code_points(document)
+          free = (0xE000..0xF8FF).lazy.reject { |code| taken.include?(code) }
+          spare = free.first(count).map { |code| code.chr(Encoding::UTF_8) }
+          return spare if spare.size == count
+
+          raise Parser::ParseError, "Unreadable line break."
+        end
+        private_class_method :spare_characters
+
+        def self.taken_code_points(document)
+          literal = document.scan(/[\ue000-\uf8ff]/).map(&:ord)
+          escaped = document.scan(YAML_CODE_ESCAPE).flatten.compact
+          literal + escaped.map { |hex| hex.to_i(16) }
+        end
+        private_class_method :taken_code_points
+
+        # A list or map is text only under the keys mermaid draws; `shape`
+        # refuses it (`validate_shape`) and any other key ignores it.
+        # `priority` is one of those: mermaid compares it by identity, so
+        # `[High]` is not the priority `High`. The one `walk` budget covers
+        # the whole body.
+        def self.stored_fields(resolved)
+          walk = { left: JS_LIST_ITEMS }
+          resolved.filter_map do |key, value|
+            next if dropped_by_mermaid?(value)
+
+            validate_shape(value) if key == "shape"
+            next if collection?(value) && !TEXT_KEYS.include?(key)
+
+            [key, js_text(value, walk)]
+          end.to_h
+        end
+        private_class_method :stored_fields
+
+        def self.collection?(value)
+          value.is_a?(Array) || value.is_a?(Hash)
+        end
+        private_class_method :collection?
+
+        def self.validate_shape(value)
+          unless value.is_a?(String)
+            raise Parser::ParseError,
+                  "Unusable shape in metadata."
+          end
+          return if value == value.downcase && !value.include?("_")
+
+          raise Parser::ParseError,
+                "No such shape: #{value}. Shape names should be lowercase."
+        end
+        private_class_method :validate_shape
+
+        # A subclass grammar whose empty body captures as [] reads as "[]",
+        # which the YAML engine takes as a mapping key with no value:
+        # the same empty metadata as an empty string.
+        def self.metadata_body_text(metadata_data)
+          metadata_data[:body].to_s
+        end
+        private_class_method :metadata_body_text
+
+        # Mermaid strips comments before lexing, so metadata never sees
+        # them - `%%{` is a directive rather than a comment and stays.
+        # Uses JavaScript's whitespace set, matching Mermaid's comment pass.
+        def self.strip_metadata_comments(body)
+          body.gsub(/(?<=\n)#{JS_SPACE}*%%(?!\{)[^\n]+\n?/o, "")
+        end
+        private_class_method :strip_metadata_comments
+
+        # The kanban lexer rewrites line breaks inside double-quoted
+        # metadata before handing the body to js-yaml.
+        def self.break_quoted_newlines(body)
+          body.gsub(/"[^"]*"/) { |run| run.gsub(QUOTED_BREAK, "<br/>") }
+        end
+        private_class_method :break_quoted_newlines
+
+        JS_SPACE = '[\t\n\v\f\r \u00a0\u1680\u2000-\u200a' \
+                   '\u2028\u2029\u202f\u205f\u3000\ufeff]'
+        QUOTED_BREAK = /\n#{JS_SPACE}*/
+        FOREIGN_BREAKS = ["\u0085", "\u2028", "\u2029"].freeze
+        YAML_CODE_ESCAPE = /\\(?:x(\h{2})|u(\h{4})|U(\h{8}))/
+        JS_LIST_ITEMS = 10_000
+        JS_LIST_DEPTH = 256
+        TEXT_KEYS = %w[assigned ticket icon label].freeze
+
+        private_constant :JS_SPACE, :QUOTED_BREAK, :FOREIGN_BREAKS,
+                         :YAML_CODE_ESCAPE, :JS_LIST_ITEMS, :JS_LIST_DEPTH,
+                         :TEXT_KEYS
+
+        # `null`, `false`, `0` and `""` are all falsy to mermaid, which
+        # skips the key rather than failing on it - the same table
+        # Builders::Flowchart#truthy? applies to its own resolved values.
+        def self.dropped_by_mermaid?(value)
+          case value
+          when nil, false, 0, "" then true
+          else value.is_a?(Float) && value.nan?
+          end
+        end
+        private_class_method :dropped_by_mermaid?
+
+        # Mermaid draws `.toString()` of what js-yaml resolved: numbers and
+        # booleans as JavaScript prints them (`0x10` is "16"), a list as its
+        # items joined by commas (`[one, two]` is "one,two"), a map as
+        # "[object Object]". An alias repeats a list by reference, so
+        # `JS_LIST_ITEMS` caps the items joined and `JS_LIST_DEPTH` the
+        # nesting, as `Source::Frontmatter` bounds its own walk; mmdc draws
+        # some bodies this refuses.
+        #
+        # @param walk [Hash] items still allowed to be joined, body-wide
+        # @param ancestors [Array<Array>] lists being joined; one holding
+        #   itself joins as "" the way JavaScript's `join` does
+        def self.js_text(value, walk, ancestors = [])
+          case value
+          when Numeric then Etassia::JsNumber.stringify(value)
+          when Hash then "[object Object]"
+          when Array then js_join(value, walk, ancestors)
+          else value.to_s
+          end
+        end
+        private_class_method :js_text
+
+        def self.js_join(list, walk, ancestors)
+          return "" if ancestors.any? { |outer| outer.equal?(list) }
+
+          refuse_list("nested too deeply") if ancestors.size >= JS_LIST_DEPTH
+          list.map do |item|
+            walk[:left] -= 1
+            refuse_list("too large") if walk[:left].negative?
+
+            js_text(item, walk, ancestors + [list])
+          end.join(",")
+        end
+        private_class_method :js_join
+
+        def self.refuse_list(reason)
+          raise Parser::ParseError, "Metadata list #{reason}."
+        end
+        private_class_method :refuse_list
+
+        # Transform the lines array into columns and cards
+        rule(lines: subtree(:lines)) do
+          builder = BoardBuilder.new
+          lines_array = Array(lines)
+
+          lines_array.each do |line_data|
+            # An empty line never captures anything, so it contributes no
+            # entry at all to this array rather than a Hash lacking keys -
+            # this Hash check is the only filter empty lines need. It is
+            # NOT a stand-in for requiring `:id`: an unlabelled shaped item
+            # (`(text)`) is a Hash with no `:id` key and is a real item.
+            next unless line_data.is_a?(Hash)
+
+            builder.add_line(line_data)
+          end
+
+          builder.finalize
+
+          {
+            columns: builder.columns,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/builders/mindmap.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for Mindmap diagrams
+      class Mindmap < Parslet::Transform
+        # Helper class to build mindmap tree from indented nodes
+        class TreeBuilder
+          # The first matching rule wins, in this order.
+          SHAPE_NAMES = %w[circle bang cloud hexagon square round].freeze
+          NODE_KEYS = %i[
+            content icon classes shape_circle shape_bang shape_cloud
+            shape_hexagon shape_square shape_round
+          ].freeze
+
+          attr_reader :root, :all_nodes
+
+          def initialize
+            @all_nodes = []
+            @root = nil
+            @level_stack = []
+            @pending_icon = nil
+            @pending_classes = []
+            @min_indent = nil
+          end
+
+          def add_node(node_data)
+            if node_data[:icon]
+              return apply_to_previous(:icon, node_data[:icon].to_s)
+            end
+            return apply_classes(node_data[:classes]) if node_data[:classes]
+
+            add_tree_node(node_data)
+          end
+
+          def node_data?(node_data)
+            NODE_KEYS.any? { |key| node_data[key] }
+          end
+
+          def apply_to_previous(attribute, value)
+            @all_nodes.last[attribute] = value if @all_nodes.last
+          end
+
+          def apply_classes(classes)
+            apply_to_previous(:classes, classes.to_s.split(/\s+/))
+          end
+
+          def add_tree_node(node_data)
+            indent_size = get_indent_size(node_data[:indent])
+            if @min_indent.nil? || indent_size < @min_indent
+              @min_indent = indent_size
+            end
+            level = calculate_level(node_data[:indent])
+            node = node_entry(node_data, level, indent_size)
+            @all_nodes << node
+            link_node(node, level)
+          end
+
+          def node_entry(node_data, level, indent_size)
+            {
+              id: "node-#{@all_nodes.size}",
+              content: extract_content(node_data), level: level,
+              shape: extract_shape(node_data), icon: nil, classes: [],
+              children: [], _indent_size: indent_size
+            }
+          end
+
+          def link_node(node, level)
+            if level.zero?
+              @root = node
+              @level_stack = [node]
+            else
+              attach_to_parent(node, find_parent(level))
+              @level_stack = @level_stack[0..(level - 1)] + [node]
+            end
+          end
+
+          def attach_to_parent(node, parent)
+            return unless parent
+
+            parent[:children] << node
+            node[:parent] = parent
+          end
+
+          def finalize
+            # Nothing to link if no real node was ever added.
+            return if @min_indent.nil?
+
+            # Rebuild hierarchy directly from each node's raw indentation,
+            # not a level number banded to a fixed 2- or 4-space step. The
+            # banded approach broke whenever one level's indent jumped by an
+            # amount the fixed band didn't expect (e.g. a first indent step
+            # of 4 columns from a zero-indent root): it produced a level
+            # with no entry below it in the stack, so the child was computed
+            # but never linked as anyone's child.
+            rebuild_hierarchy
+          end
+
+          # A `%%` comment line embedded inside a multi-line round-shape
+          # node's own content (e.g. "root(\n  one\n  %% hidden\n  two\n)").
+          # Mermaid strips every such line, terminator included, before its
+          # node lexer ever runs, but only when the `%%` starts a REAL
+          # source line -- one already preceded by a newline -- and only
+          # when at least one character follows it; `root(%% keep this)`
+          # is one physical line (the `%%` sits after "root(", not at a
+          # line start) so mermaid renders it literally, and a bare "%%"
+          # with nothing after it is not a comment either. `^` matched at
+          # the start of the extracted content string too, which isn't a
+          # real line start unless something upstream already consumed a
+          # newline to get there; `(?<=\n)` requires an actual newline
+          # immediately before, without consuming it, so the string's own
+          # start is never mistaken for one. Mirrors
+          # Builders::Flowchart#strip_metadata_comments (flowchart.rb),
+          # the same rule for a node's `@{...}` metadata block -- including
+          # its indentation class: mermaid's own comment-strip regex uses
+          # JavaScript's `\s`, wider than ASCII space/tab (e.g. it matches a
+          # no-break space), so `[ \t]` alone left a comment unrecognised
+          # when it was indented with one.
+          ROUND_COMMENT_INDENT = '[\t\n\v\f\r \u00a0\u1680\u2000-\u200a' \
+                                 '\u2028\u2029\u202f\u205f\u3000\ufeff]'
+          ROUND_COMMENT_LINE = Regexp.new(
+            "(?<=\\n)#{ROUND_COMMENT_INDENT}*%%(?!\\{)" \
+            "[^\\r\\n]+\\r?\\n?",
+          )
+
+          private
+
+          def rebuild_hierarchy
+            @root = nil
+            # Stack of [indent_size, node] for the current ancestor chain:
+            # each new node pops every entry whose indent is >= its own
+            # (those are siblings or deeper nodes it isn't nested under),
+            # then attaches under whatever remains on top.
+            indent_stack = []
+            @all_nodes.each { |node| rebuild_node(node, indent_stack) }
+          end
+
+          def rebuild_node(node, indent_stack)
+            indent_size = prepare_for_rebuild(node)
+            discard_siblings(indent_stack, indent_size)
+            attach_rebuilt_node(node, indent_stack)
+            indent_stack << [indent_size, node]
+          end
+
+          def prepare_for_rebuild(node)
+            indent_size = node.delete(:_indent_size) || 0
+            node[:children] = []
+            node.delete(:parent)
+            indent_size
+          end
+
+          def discard_siblings(indent_stack, indent_size)
+            while indent_stack.any? && indent_stack.last[0] >= indent_size
+              indent_stack.pop
+            end
+          end
+
+          def attach_rebuilt_node(node, indent_stack)
+            return install_root(node) if indent_stack.empty?
+
+            parent = indent_stack.last[1]
+            node[:level] = parent[:level] + 1
+            attach_to_parent(node, parent)
+          end
+
+          # A second node with no ancestor is a second root. Mermaid rejects
+          # it rather than silently discarding the first root and its subtree.
+          def install_root(node)
+            if @root
+              raise Etassia::Parser::ParseError, "Multiple roots are illegal"
+            end
+
+            node[:level] = 0
+            @root = node
+          end
+
+          def get_indent_size(indent_data)
+            return 0 if indent_data.nil?
+            return 0 if indent_data.is_a?(Array) && indent_data.empty?
+
+            indent_string(indent_data).length
+          end
+
+          def calculate_level(indent_data)
+            return 0 if indent_data.nil?
+            return 0 if indent_data.is_a?(Array) && indent_data.empty?
+
+            indent_str = indent_string(indent_data)
+            return 0 if indent_str.empty?
+
+            spaces = indent_str.length
+            spaces.even? ? spaces / 2 : spaces / 4
+          end
+
+          def indent_string(indent_data)
+            separator = ""
+            return indent_data.join(separator) if indent_data.is_a?(Array)
+
+            indent_data.to_s
+          end
+
+          def extract_content(node_data)
+            return "" unless node_data[:content]
+
+            content = node_data[:content].to_s
+            return content unless node_data[:shape_round]
+
+            round_content(content, node_data[:round_quoted])
+          end
+
+          # Quoting protects the leading newline but not a real comment line:
+          # Mermaid strips those comments before quote lexing.
+          def round_content(content, quoted)
+            quoted ? strip_round_comments(content) : strip_round_extras(content)
+          end
+
+          def strip_round_comments(content)
+            content.gsub(ROUND_COMMENT_LINE, "")
+          end
+
+          def strip_round_extras(content)
+            # Drop embedded comment-only lines first (matching mermaid's own
+            # pre-lexer pass), then the one leading newline that a
+            # multi-line node's own opening "(\n" legitimately introduces --
+            # mermaid's rendered output drops exactly that line break and
+            # nothing else. `\r?` handles a caller that passes CRLF source
+            # straight to this parser without going through
+            # `Source.normalize` (Engine's real render path always does).
+            strip_round_comments(content).sub(/\A\r?\n/, "")
+          end
+
+          def extract_shape(node_data)
+            SHAPE_NAMES.find { |name| node_data[:"shape_#{name}"] } ||
+              "default"
+          end
+
+          def find_parent(level)
+            # Parent is the last node at level - 1; level 0 is the root and
+            # never asks.
+            @level_stack[level - 1]
+          end
+        end
+
+        # Transform the nodes array into a tree structure
+        rule(nodes: subtree(:nodes)) do
+          builder = TreeBuilder.new
+          nodes_array = Array(nodes)
+
+          nodes_array.each do |node_data|
+            next unless node_data.is_a?(Hash)
+
+            next unless builder.node_data?(node_data)
+
+            builder.add_node(node_data)
+          end
+
+          # Finalize to adjust levels and rebuild hierarchy
+          builder.finalize
+
+          {
+            root: builder.root,
+            nodes: builder.all_nodes,
+          }
+        end
+      end
+    end
+  end
+end