etassia 0.1.0

data/lib/etassia/parser/user_journey.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "parslet"
+require_relative "base"
+require_relative "../error/score_error"
+require_relative "native/builders/user_journey"
+require_relative "../diagram/user_journey"
+
+module Etassia
+  module Parser
+    # Parslet grammar for User Journey diagrams
+    class UserJourneyGrammar < Parslet::Parser
+      rule(:sp) { match('[ \t]').repeat(1) }
+      rule(:sp?) { sp.maybe }
+      rule(:nl) { str("\n") }
+
+      rule(:journey) { str("journey") >> sp? >> (nl | any.absent?) }
+      rule(:title_decl) do
+        sp? >> str("title") >> sp >> text_line.as(:title) >>
+          (nl | any.absent?)
+      end
+      rule(:section_decl) do
+        sp? >> str("section") >> sp >> text_line.as(:section) >>
+          (nl | any.absent?)
+      end
+      # accTitle/accDescr text is parsed and discarded: no Diagram::UserJourney
+      # attribute holds it yet.
+      rule(:accessibility_decl) { acc_descr_block | acc_line }
+
+      # mermaid's own lexer matches these keywords case-insensitively (e.g.
+      # `ACCDESCR:` is a description, not a task literally named "ACCDESCR").
+      # Mirrors Grammars::StateDiagram#word_ci; duplicated rather than shared
+      # because that method is private to a `StateDiagram < Common` subclass
+      # and this grammar isn't part of that hierarchy.
+      def word_ci(word)
+        word.each_char
+          .map { |ch| match["#{ch.downcase}#{ch.upcase}"] }
+          .reduce(:>>)
+      end
+
+      # The gap around `:` must stay optional -- mermaid accepts `accDescr : x`.
+      # `sp?` here is ASCII-only by design (mermaid's wider `\s` is a known,
+      # unclosed gap; see acc_line_space for where the wider set IS required).
+      rule(:acc_line) do
+        sp? >> (word_ci("accTitle") | word_ci("accDescr")) >> sp? >> str(":") >>
+          (nl.absent? >> any).repeat >> (nl | any.absent?)
+      end
+
+      rule(:acc_descr_open) { sp? >> word_ci("accDescr") >> sp? >> str("{") }
+
+      # The braced form. The closing brace ends the block; nothing after it on
+      # the same line is required -- do not add a line-end requirement here,
+      # it re-triggers the quadratic rescan `acc_block_body`'s invariant below
+      # exists to prevent (measurements in the gate record).
+      #
+      # Do not make this brace-aware: the FIRST unescaped `}` must close the
+      # block, even one that belongs to unrelated text further down the
+      # source, to match the oracle's own lexer (see gate record).
+      rule(:acc_descr_block) do
+        acc_descr_open >> acc_block_body >> str("}")
+      end
+
+      # INVARIANT: every alternative reachable from `acc_block_comment` must be
+      # LINE-BOUNDED (its repeats carry `acc_nl.absent?`, or it consumes a
+      # single character). This repeat visits every position in the block, so
+      # an alternative able to run to the end of the source makes the whole
+      # parse quadratic in the block's length. Anything added to
+      # `acc_block_comment` inherits this constraint.
+      # Consume ordinary text without checking comment openers per character.
+      # Stop before every line terminator so comments retain their boundaries.
+      rule(:acc_block_body) do
+        (match['[^}\n\r\u2028\u2029]'].repeat(1) |
+          acc_block_comment | (str("}").absent? >> any)).repeat
+      end
+
+      # An opener whose brace never closes makes the whole source unparseable,
+      # so `line` (below) must refuse it here rather than let it fall through
+      # to `task_line` -- the fallthrough re-scans the rest of the source per
+      # line and is quadratic. This deliberately refuses some sources the
+      # oracle also refuses, so it never narrows what the grammar accepts.
+      rule(:acc_descr_unclosed) do
+        acc_descr_open >> acc_block_body >> any.absent?
+      end
+
+      # Mermaid strips directive lines, then comment lines, before parsing
+      # anything, so a `}` inside either must not act as a delimiter here.
+      rule(:acc_block_comment) { acc_directive | acc_comment_line }
+
+      # `%%{` opens a DIRECTIVE, not a comment -- `acc_comment_line` must
+      # refuse it, or the `}` inside a directive's JSON body could close the
+      # accessibility block early. The tail `}%%` is REQUIRED (mermaid makes
+      # it optional) so an unterminated directive is refused, matching the
+      # oracle. Known divergence: mermaid strips `%%{x}%%` mid-line; this
+      # treats it as text.
+      #
+      # Do not make the body unbounded -- it must stay LINE-BOUNDED per the
+      # invariant on `acc_block_body`, or it reintroduces a quadratic scan.
+      rule(:acc_directive) do
+        acc_nl >> acc_line_space.repeat >> str("%%{") >>
+          (acc_nl.absent? >> str("}%%").absent? >> any).repeat >> str("}%%")
+      end
+
+      rule(:acc_comment_line) do
+        acc_nl >> acc_line_space.repeat >> str("%%") >> str("{").absent? >>
+          (acc_nl.absent? >> any).repeat
+      end
+
+      # `nl` stays LF-only; this rule is wider (ECMAScript's four line
+      # terminators) because it alone decides whether a `}` is content or a
+      # delimiter -- a narrower set here loses a task in silence (CR/U+2028/
+      # U+2029 before `%% }` would close the block and drop it).
+      rule(:acc_nl) { match['\n\r\u2028\u2029'] }
+
+      # Mermaid's whitespace set (as flowchart's `line_space` spells it),
+      # minus the two terminators `acc_nl` already claims. Only the comment
+      # and directive rules use it, because that's the one place a too-narrow
+      # set loses content in SILENCE. Do NOT fold this into `acc_nl` -- they
+      # must stay disjoint or a run of these chars makes a valid document
+      # quadratic (each position reopens the comment rule and backtracks).
+      rule(:acc_line_space) do
+        match['\t\v\f \u00A0\u1680' \
+              '\u2000-\u200A\u202F\u205F\u3000\uFEFF']
+      end
+
+      rule(:text_line) { (nl.absent? >> str(":").absent? >> any).repeat(1) }
+      rule(:task_text) { (str(":").absent? >> nl.absent? >> any).repeat(1) }
+      rule(:actor_text) { (match('[,\n]').absent? >> any).repeat(1) }
+
+      # The actor group (second colon plus the actor list) is optional --
+      # mermaid accepts a task with only a score (`C task: 5`) -- and, once
+      # the colon is present, the actor list itself may be empty
+      # (`E task: 5:`). A space is allowed between the score and that
+      # second colon, mirroring the SP? mermaid's own lexer permits there.
+      rule(:task_line) do
+        sp? >>
+          task_text.as(:task) >> str(":") >> sp? >>
+          match("[0-9]").repeat(1).as(:score) >>
+          (sp? >> str(":") >> sp? >> actor_list.as(:actors)).maybe >>
+          sp? >> (nl | any.absent?)
+      end
+
+      rule(:actor_list) do
+        (actor_text.as(:actor) >>
+          (sp? >> str(",") >> sp? >> actor_text.as(:actor)).repeat).maybe
+      end
+
+      rule(:line) do
+        title_decl | section_decl | accessibility_decl |
+          (acc_descr_unclosed.absent? >> task_line) | comment_line | blank_line
+      end
+      rule(:comment_line) do
+        sp? >> str("%%") >> (nl.absent? >> any).repeat >> nl
+      end
+      rule(:blank_line) { sp? >> nl }
+
+      rule(:journey_doc) do
+        journey >>
+          line.repeat.as(:lines)
+      end
+
+      root(:journey_doc)
+    end
+
+    # User Journey diagram parser using Parslet
+    class UserJourney < Base
+      native :user_journey, builder: Native::Builders::UserJourney
+
+      # Both fixed-encoding grammar failures and invalid byte indexing can
+      # escape as core encoding errors. Normalize them into ParseError across
+      # the whole parse/build operation so callers see the parser contract.
+      def parse(source)
+        native_diagram(source) || ruby_diagram(source)
+      rescue EncodingError, ArgumentError => e
+        raise ParseError, "Parse error: #{e.message}"
+      end
+
+      private
+
+      def ruby_diagram(source)
+        tree = parse_with_grammar(UserJourneyGrammar.new, source)
+        build_diagram_from_tree(tree)
+      end
+
+      def build_diagram_from_tree(tree)
+        diagram = Diagram::UserJourney.new
+        current_section = nil
+        Array(tree[:lines]).each do |line|
+          current_section = consume_line(line, diagram, current_section)
+        end
+        diagram.sections << current_section if current_section
+        diagram
+      end
+
+      def consume_line(line, diagram, current_section)
+        return current_section unless line.is_a?(Hash)
+
+        return record_title(line, diagram, current_section) if line[:title]
+        return start_section(line, diagram, current_section) if line[:section]
+        return current_section unless line[:task]
+
+        add_task(line, current_section)
+      end
+
+      def record_title(line, diagram, current_section)
+        diagram.title = line[:title].to_s.strip
+        current_section
+      end
+
+      def start_section(line, diagram, current_section)
+        diagram.sections << current_section if current_section
+        Diagram::JourneySection.new(name: line[:section].to_s.strip)
+      end
+
+      def add_task(line, current_section)
+        section = current_section || Diagram::JourneySection.new(name: "")
+        section.tasks << build_task(line)
+        section
+      end
+
+      def build_task(line)
+        task = Diagram::JourneyTask.new
+        task.name = line[:task].to_s.strip
+        task.score = line[:score].to_s.to_i
+        validate_score!(task.score)
+        task.actors = task_actors(line)
+        task
+      end
+
+      def task_actors(line)
+        actor_names(line[:actors], explicit: line.key?(:actors))
+      end
+
+      def actor_names(data, explicit:)
+        if data.is_a?(Array)
+          return data.filter_map { |actor| actor_name(actor) }
+        end
+        return [data[:actor].to_s.strip] if data.is_a?(Hash) && data[:actor]
+
+        explicit ? [""] : []
+      end
+
+      def actor_name(data)
+        data[:actor].to_s.strip.then { |name| name unless name.empty? }
+      end
+
+      def validate_score!(score)
+        return if score.between?(1, 5)
+
+        raise ScoreError, "Score must be between 1 and 5, got #{score}"
+      end
+    end
+  end
+end

data/lib/etassia/parser/xy_chart.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/xy_chart"
+require_relative "builders/xy_chart"
+require_relative "native/builders/xy_chart"
+require_relative "../diagram/xy_chart"
+
+module Etassia
+  module Parser
+    # XY Chart parser for Mermaid xychart-beta diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle XY chart syntax
+    # with axes and multiple datasets.
+    #
+    # Parses XY charts with support for:
+    # - Title
+    # - X-axis with categorical or numeric values
+    # - Y-axis with range
+    # - Multiple datasets (line, bar, or named)
+    #
+    # @example Parse a simple XY chart
+    #   parser = XyChart.new
+    #   source = <<~MERMAID
+    #     xychart-beta
+    #       title "Sales Revenue"
+    #       x-axis [jan, feb, mar]
+    #       y-axis 0 --> 100
+    #       line [5, 10, 15]
+    #   MERMAID
+    #   diagram = parser.parse(source)
+    class XyChart < Base
+      grammar Grammars::XyChart
+      builder Builders::XyChart
+      native :xychart, builder: Native::Builders::XyChart
+
+      # Assembles the diagram from the builder's intermediate result; the
+      # native builder shares it.
+      #
+      # @param result [Hash] title, x_axis, y_axis and datasets
+      # @return [Diagram::XyChart]
+      def create_diagram(result)
+        diagram = Diagram::XyChart.new
+        diagram.title = result[:title]
+        assign_axes(diagram, result)
+        append_datasets(diagram, result[:datasets])
+        diagram
+      end
+
+      private
+
+      def assign_axes(diagram, result)
+        diagram.x_axis = create_x_axis(result[:x_axis]) if result[:x_axis]
+        diagram.y_axis = create_y_axis(result[:y_axis]) if result[:y_axis]
+      end
+
+      def append_datasets(diagram, datasets)
+        datasets.each_with_index do |data, index|
+          diagram.add_dataset(build_dataset(data, index))
+        end
+      end
+
+      def build_dataset(data, index)
+        dataset = Diagram::XYDataset.new(
+          "dataset_#{index}", data[:label], data[:chart_type]
+        )
+        dataset.values = data[:values]
+        dataset
+      end
+
+      def create_x_axis(axis_data)
+        axis = Diagram::XYAxis.new
+        axis.label = axis_data[:label]
+        assign_x_values(axis, axis_data[:values])
+        axis
+      end
+
+      def assign_x_values(axis, values)
+        if values.all?(Numeric)
+          axis.type = :numeric
+          axis.values = values
+        else
+          axis.type = :categorical
+          axis.values = values.map(&:to_s)
+        end
+      end
+
+      def create_y_axis(axis_data)
+        axis = Diagram::XYAxis.new
+        axis.label = axis_data[:label]
+        axis.type = :numeric
+        axis.min = axis_data[:min]
+        axis.max = axis_data[:max]
+        axis
+      end
+    end
+  end
+end

data/lib/etassia/parser.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "parser/base"
+require_relative "notation/mermaid"
+
+module Etassia
+  module Parser
+    # A fresh parser for a diagram type, found by naming convention
+    # (`:pie` -> `Parser::Pie`). Never cached.
+    #
+    # @param type [Symbol] a key of {Notation::Mermaid::TYPES}
+    # @raise [Engine::DiagramTypeError] when the type is unknown
+    # @raise [ParseError] when the type has no parser class
+    def self.for(type)
+      Notation::Mermaid.layer_class(self, type, ParseError).new
+    end
+  end
+end

data/lib/etassia/renderer/architecture.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../layout/architecture"
+
+module Etassia
+  module Renderer
+    # Emits SVG from final, typed architecture geometry.
+    class Architecture < Base
+      ICON_GLYPHS = {
+        "database" => "⬢",
+        "server" => "▦",
+        "disk" => "◎",
+        "cloud" => "☁",
+        "internet" => "◈",
+        "browser" => "⊞",
+      }.freeze
+
+      UNKNOWN_ICON_GLYPH = "?"
+
+      # @param scene [Layout::Architecture::Scene] final canvas geometry
+      # @return [Svg::Document] rendered SVG document
+      def render(scene)
+        svg = create_document(scene)
+        render_groups(scene, svg)
+        scene.edges.each { |edge| render_edge(edge, svg) }
+        render_nodes(scene, svg)
+        svg
+      end
+
+      protected
+
+      def render_groups(scene, svg)
+        scene.children.select { |node| node.kind == "group" }
+          .each { |group| render_group(group, svg) }
+      end
+
+      def render_nodes(scene, svg)
+        scene.children.reject { |node| node.kind == "group" }
+          .each { |node| render_node(node, svg) }
+      end
+
+      def named_architecture_group(identifier)
+        Svg::Group.new.tap { |group| group.id = identifier }
+      end
+
+      def render_group(node, svg)
+        group = named_architecture_group("group-#{node.id}")
+        children = group.children
+        children << group_boundary(node)
+        children << group_label(node) unless node.labels.empty?
+        children << icon(node, 20) if node.icon
+        svg << group
+      end
+
+      def group_boundary(node)
+        Svg::Rect.new.tap do |rect|
+          apply_box(rect, node)
+          rect.fill = theme_color(:group_background)
+          rect.fill_opacity = "0.3"
+          rect.stroke = theme_color(:architecture_group_border)
+          rect.stroke_width = "2"
+          rect.stroke_dasharray = "5,5"
+          rect.rx = "8"
+          rect.ry = "8"
+        end
+      end
+
+      def group_label(node)
+        positioned_text(node.labels.first).tap do |text|
+          text.fill = theme_color(:architecture_group_label)
+        end
+      end
+
+      def render_node(node, svg)
+        if node.kind == "junction"
+          render_junction(node, svg)
+        else
+          render_service(node, svg)
+        end
+      end
+
+      def render_service(node, svg)
+        group = named_architecture_group("service-#{node.id}")
+        children = group.children
+        children << service_box(node)
+        children << icon(node, 24) if node.icon
+        children << service_label(node) unless node.labels.empty?
+        svg << group
+      end
+
+      def service_box(node)
+        return fallback_service_box(node) if node.icon.to_s.empty?
+
+        Svg::Rect.new.tap do |rect|
+          apply_box(rect, node)
+          apply_theme_to_node(rect)
+          rect.rx = "5"
+          rect.ry = "5"
+        end
+      end
+
+      def fallback_service_box(node)
+        Svg::Path.new.tap do |path|
+          path.d = fallback_service_path(node)
+          path.fill = "none"
+          path.stroke = theme_color(:node_stroke)
+          path.stroke_width = "2"
+          path.stroke_dasharray = "8"
+        end
+      end
+
+      def fallback_service_path(node)
+        top = node.y + 5
+        right = node.x + node.width
+        bottom = node.y + node.height
+        fallback_service_commands(node, top, right, bottom)
+      end
+
+      def fallback_service_commands(node, top, right, bottom)
+        "M #{node.x} #{bottom} V #{top} Q #{node.x} #{node.y} " \
+          "#{node.x + 5} #{node.y} H #{right - 5} Q #{right} #{node.y} " \
+          "#{right} #{top} V #{bottom} H #{node.x} Z"
+      end
+
+      def icon(node, size)
+        Svg::Text.new.tap do |text|
+          position_icon(text, node)
+          text.content = icon_glyph(node.icon)
+          text.font_size = size.to_s
+          align_service_icon(text, node)
+          text.fill = theme_color(:edge_color)
+        end
+      end
+
+      def position_icon(text, node)
+        text.x = node.icon_x
+        text.y = node.icon_y
+      end
+
+      def align_service_icon(text, node)
+        return unless node.kind == "service"
+
+        text.text_anchor = "middle"
+        text.dominant_baseline = "middle"
+      end
+
+      def service_label(node)
+        positioned_text(node.labels.first).tap do |text|
+          text.fill = theme_color(:label_text)
+          text.font_family = label_font_family
+          text.dominant_baseline = "middle"
+        end
+      end
+
+      def positioned_text(label)
+        Svg::Text.new(
+          x: label.x, y: label.y, content: label.text,
+          font_size: number_string(label.font_size),
+          font_weight: label.font_weight,
+          text_anchor: label.text_anchor
+        )
+      end
+
+      def label_font_family
+        theme_typography(:font_family) || "Arial, Helvetica, sans-serif"
+      end
+
+      def render_junction(node, svg)
+        group = named_architecture_group("junction-#{node.id}")
+        group.children << junction_circle(node)
+        svg << group
+      end
+
+      def junction_circle(node)
+        Svg::Circle.new.tap do |circle|
+          circle.cx = node.center_x
+          circle.cy = node.center_y
+          circle.r = node.radius
+          apply_theme_to_node(circle)
+        end
+      end
+
+      def render_edge(edge, svg)
+        group = named_architecture_group("edge-#{edge.source}-#{edge.target}")
+        group.children << edge_path(edge)
+        unless edge.labels.empty?
+          group.children << edge_label(edge.labels.first)
+        end
+        svg << group
+      end
+
+      def edge_path(edge)
+        Svg::Path.new.tap do |path|
+          path.d = section_path(edge.sections.first)
+          path.fill = "none"
+          apply_theme_to_edge(path)
+        end
+      end
+
+      def section_path(section)
+        points = [section.start_point, *section.bend_points, section.end_point]
+        points.map.with_index do |point, index|
+          "#{index.zero? ? 'M' : 'L'} #{point.x} #{point.y}"
+        end.join(" ")
+      end
+
+      def edge_label(label)
+        positioned_text(label).tap do |text|
+          text.fill = theme_color(:edge_color)
+        end
+      end
+
+      def number_string(value)
+        value.to_i == value ? value.to_i.to_s : value.to_s
+      end
+
+      def apply_box(rect, node)
+        rect.x = node.x
+        rect.y = node.y
+        rect.width = node.width
+        rect.height = node.height
+      end
+
+      def icon_glyph(icon_name)
+        ICON_GLYPHS.fetch(icon_name.split(":").last, UNKNOWN_ICON_GLYPH)
+      end
+      private :render_groups, :render_nodes, :named_architecture_group,
+              :position_icon, :align_service_icon, :junction_circle
+    end
+  end
+end