etassia 0.1.0

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

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require_relative "../../diagram/gantt"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for converting Parslet parse tree to Gantt diagram model.
+      #
+      # Converts the parse tree output from Grammars::Gantt into a
+      # fully-formed Diagram::Gantt object with sections and tasks.
+      class Gantt
+        TAG_KEYWORDS = %w[done active crit milestone].freeze
+        DURATION_PATTERN = /\A\d+(?:\.\d+)?(?:ms|[Mdhmswy])\z/
+        ITEM_HANDLERS = {
+          header: :process_header,
+          title: :process_title,
+          date_format: :process_date_format,
+          axis_format: :process_axis_format,
+          tick_interval: :process_tick_interval,
+          excludes: :process_excludes,
+          weekend: :process_weekend,
+          inclusive_end_dates: :process_inclusive_end_dates,
+          today_marker: :process_today_marker,
+          acc_title: :process_acc_title,
+          acc_descr: :process_acc_descr,
+          section: :process_section,
+          click_id: :process_click,
+          task_entry: :process_task,
+        }.freeze
+        private_constant :TAG_KEYWORDS, :DURATION_PATTERN, :ITEM_HANDLERS
+
+        # Transform parse tree into Gantt diagram.
+        #
+        # @param tree [Array, Hash] Parslet parse tree
+        # @return [Diagram::Gantt] the gantt chart diagram model
+        def apply(tree)
+          diagram = Diagram::Gantt.new
+          @current_section = nil
+          @click_map = {}
+          process_tree(diagram, tree)
+          apply_click_handlers(diagram)
+          diagram
+        end
+
+        private
+
+        # Tree structure: array with header and statements
+        def process_tree(diagram, tree)
+          return tree.each { |item| process_item(diagram, item) } if
+            tree.is_a?(Array)
+
+          process_item(diagram, tree) if tree.is_a?(Hash)
+        end
+
+        def process_item(diagram, item)
+          return unless item.is_a?(Hash)
+
+          ITEM_HANDLERS.each do |key, handler|
+            send(handler, diagram, item) if item.key?(key)
+          end
+        end
+
+        def process_header(diagram, item)
+          # Header is just the 'gantt' keyword, nothing to extract
+        end
+
+        def process_title(diagram, item)
+          diagram.title = extract_text(item[:title])
+        end
+
+        def process_date_format(diagram, item)
+          diagram.date_format = extract_text(item[:date_format])
+        end
+
+        def process_axis_format(diagram, item)
+          diagram.axis_format = extract_text(item[:axis_format])
+        end
+
+        def process_tick_interval(diagram, item)
+          diagram.tick_interval = extract_text(item[:tick_interval])
+        end
+
+        def process_excludes(diagram, item)
+          excludes_text = extract_text(item[:excludes])
+          diagram.excludes << excludes_text unless excludes_text.empty?
+        end
+
+        def process_weekend(diagram, item)
+          diagram.weekend = extract_text(item[:weekend])
+        end
+
+        def process_inclusive_end_dates(diagram, _item)
+          diagram.inclusive_end_dates = true
+        end
+
+        def process_today_marker(diagram, item)
+          diagram.today_marker = extract_text(item[:today_marker])
+        end
+
+        def process_acc_title(diagram, item)
+          # Store as metadata (not currently in model)
+        end
+
+        def process_acc_descr(diagram, item)
+          # Store as metadata (not currently in model)
+        end
+
+        def process_section(diagram, item)
+          section_name = extract_text(item[:section])
+          @current_section = Diagram::GanttSection.new(section_name)
+          diagram.sections << @current_section
+        end
+
+        def process_click(_diagram, item)
+          click_id = extract_text(item[:click_id])
+          if item[:href]
+            @click_map[click_id] = {
+              type: :href, value: extract_text(item[:href])
+            }
+          elsif item[:callback]
+            @click_map[click_id] = {
+              type: :callback, value: extract_text(item[:callback])
+            }
+          end
+        end
+
+        def process_task(diagram, item)
+          ensure_current_section(diagram)
+          task_entry = item[:task_entry]
+          task = build_task(task_entry)
+          @current_section.tasks << task
+        end
+
+        def ensure_current_section(diagram)
+          return if @current_section
+
+          @current_section = Diagram::GanttSection.new("Default")
+          diagram.sections << @current_section
+        end
+
+        def build_task(task_entry)
+          task = Diagram::GanttTask.new
+          task.description = extract_text(task_entry[:description])
+          process_task_details(task, task_entry[:task_details]) if
+            task_entry[:task_details]
+          task
+        end
+
+        # Task details are a comma-separated list of fields (mermaid allows
+        # tags, an id, "after"/"until", a date, and a duration). Tags are
+        # unambiguous keywords, consumed first regardless of position. What
+        # is left occupies id/start/end — THREE positional slots — and
+        # mermaid classifies by POSITION when there are exactly three (the
+        # id is always first, even when its text happens to look like a
+        # date, corpus gantt/NNN). An "after"/"until" dependency fills the
+        # start slot the same as a bare date would, so it must still count
+        # towards that three-slot rule; only once the id is settled does it
+        # get stripped out on its own.
+        #
+        # Outside the three-slot case there is no id field at all — every
+        # remaining value is a start/end/duration, by position, never by
+        # shape. Measured against mmdc: `T: 20240101, 20240103` under
+        # `dateFormat YYYYMMDD` renders both compact fields as dates with no
+        # id (mermaid auto-generates one); a single non-date, non-duration
+        # field on its own (`T: someid`) is a parse ERROR in mermaid, not an
+        # id. So `classify_value_field` never falls back to treating a field
+        # as an id — DURATION_PATTERN is the only shape test, and everything
+        # else is a date, whether or not it looks like one (this is also
+        # what keeps a leftover compact date from stomping the id that the
+        # three-slot rule already assigned).
+        def process_task_details(task, details)
+          return unless details.is_a?(Hash)
+
+          fields = extract_task_fields(details[:parts])
+          positional_fields = reject_tag_fields(task, fields)
+          task.id = positional_fields.shift if positional_fields.length == 3
+
+          value_fields = reject_dependency_fields(task, positional_fields)
+
+          dates = []
+          value_fields.each { |field| classify_value_field(task, field, dates) }
+          assign_dates(task, dates)
+        end
+
+        def extract_task_fields(parts)
+          Array(parts.is_a?(Array) ? parts : [parts]).map do |part|
+            extract_text(part[:field])
+          end
+        end
+
+        def reject_tag_fields(task, fields)
+          fields.reject do |field|
+            next false unless TAG_KEYWORDS.include?(field)
+
+            task.tags << field
+            true
+          end
+        end
+
+        def reject_dependency_fields(task, fields)
+          fields.reject do |field|
+            case field
+            when /\Aafter\s+(.+)\z/
+              task.after_task = Regexp.last_match(1)
+              true
+            when /\Auntil\s+(.+)\z/
+              task.until_task = Regexp.last_match(1)
+              true
+            end
+          end
+        end
+
+        def classify_value_field(task, field, dates)
+          if field.match?(DURATION_PATTERN)
+            task.duration = field
+          else
+            dates << field
+          end
+        end
+
+        # A lone date is normally the start. After an "after" dependency,
+        # though, the dependency supplies the start (see
+        # Gantt#resolve_task_dependency, which reads calculated
+        # start from the referenced task and never consults `start_date`
+        # once `after_task` is set) — so a single trailing date there is the
+        # end, or `resolve_task_dependency` never finds an end to compute.
+        def assign_dates(task, dates)
+          if dates.length == 1 && task.after_task
+            task.end_date = dates[0]
+          else
+            task.start_date = dates[0] if dates[0]
+            task.end_date = dates[1] if dates[1]
+          end
+        end
+
+        def apply_click_handlers(diagram)
+          diagram.sections.flat_map(&:tasks).each do |task|
+            apply_click_handler(task)
+          end
+        end
+
+        def apply_click_handler(task)
+          click_info = @click_map[task.id]
+          return unless task.id && click_info
+
+          if click_info[:type] == :href
+            task.click_href = click_info[:value]
+          elsif click_info[:type] == :callback
+            task.click_callback = click_info[:value]
+          end
+        end
+
+        def extract_text(value)
+          case value
+          when Hash
+            value.values.first.to_s
+          when String
+            value
+          else
+            value.to_s
+          end.strip
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for Git Graph diagrams
+      class GitGraph < Parslet::Transform
+        # Current state tracking
+        class State
+          attr_accessor :current_branch, :branches, :commits, :commit_counter,
+                        :acc_title, :acc_description
+
+          # An empty capture comes back from Parslet as an Array, not "".
+          def self.captured_text(captured)
+            captured.is_a?(Array) ? "" : captured.to_s
+          end
+
+          ESCAPES = {
+            "b" => "\b", "f" => "\f", "n" => "\n", "r" => "\r",
+            "t" => "\t", "v" => "\v", "0" => "\0"
+          }.freeze
+          private_constant :ESCAPES
+
+          OPTION_KEYS = {
+            id: :id, type: :type,
+            parent: :cherry_pick_parent
+          }.freeze
+          private_constant :OPTION_KEYS
+
+          STATEMENT_HANDLERS = {
+            commit: :process_commit,
+            branch: :process_branch,
+            checkout: :process_checkout,
+            switch: :process_switch,
+            merge: :process_merge,
+            cherry_pick: :process_cherry_pick,
+            acc_title: :process_acc_title,
+          }.freeze
+          private_constant :STATEMENT_HANDLERS
+
+          # A backslash in a quoted string escapes the next character: `\n`
+          # and the other control escapes become the control character,
+          # anything else (`\"`, `\\`, `\x`) becomes itself.
+          def self.unquote(captured)
+            captured_text(captured).gsub(/\\(.)/m) do
+              ESCAPES.fetch(Regexp.last_match(1), Regexp.last_match(1))
+            end
+          end
+
+          # Mermaid trims every line of a directive's text.
+          def self.directive_text(captured)
+            captured_text(captured).strip.split("\n").map(&:strip).join("\n")
+          end
+
+          def initialize(main_branch_name = "main")
+            @current_branch = main_branch_name
+            @branches = {
+              main_branch_name => { order: 0, created_at: nil },
+            }
+            @commits = []
+            @commit_counter = 0
+          end
+
+          def add_commit(options = {})
+            @commit_counter += 1
+            commit_id = options[:id] || "commit-#{@commit_counter}"
+            validate_commit_id!(commit_id, options)
+            commit = commit_identity(commit_id, options).merge(
+              commit_semantics(options),
+            )
+            @commits << commit
+            commit
+          end
+
+          def process(statements)
+            Array(statements).each do |statement|
+              process_statement(statement) if statement.is_a?(Hash)
+            end
+            self
+          end
+
+          def to_h
+            {
+              acc_title: acc_title,
+              acc_description: acc_description,
+              main_branch_name: branches.first.first,
+              commits: commits,
+              branches: branches.map { |name, info| branch_entry(name, info) },
+            }
+          end
+
+          def extract_options(options)
+            Array(options).each_with_object({}) do |option, result|
+              next unless option.is_a?(Hash)
+
+              OPTION_KEYS.each do |source, target|
+                assign_option(result, option, source, target)
+              end
+              assign_tag(result, option) if option.key?(:tag)
+              if option[:message]
+                result[:message] = State.unquote(option[:message])
+              end
+            end
+          end
+
+          def assign_option(result, option, source, target)
+            value = option[source]&.to_s
+            return if value.nil?
+
+            result[target] = value
+          end
+
+          def assign_tag(result, option)
+            value = option[:tag]&.to_s
+            value = "" if value == '""'
+            result[:tags] ||= []
+            result[:tags] << value
+            result[:tag] = value unless value.empty?
+          end
+
+          def commit_identity(commit_id, options)
+            {
+              id: commit_id,
+              message: options[:message],
+              type: options[:type] || "NORMAL",
+              tag: options[:tag],
+              tags: options.fetch(:tags, []),
+              branch_name: @current_branch,
+              parent_ids: options[:parent_ids] || find_parents,
+            }
+          end
+
+          def commit_semantics(options)
+            {
+              is_merge: options[:is_merge] || false,
+              merge_branch: options[:merge_branch],
+              is_cherry_pick: options[:is_cherry_pick] || false,
+              cherry_pick_parent: options[:cherry_pick_parent],
+            }
+          end
+
+          def add_branch(name, order = nil)
+            return if @branches.key?(name)
+
+            @branches[name] = {
+              order: order,
+              parent_branch: @current_branch,
+              created_at: branch_tip(@current_branch),
+            }
+          end
+
+          def checkout_branch(name)
+            unless @branches.key?(name)
+              raise Parser::ParseError, "Unknown branch: #{name}."
+            end
+
+            @current_branch = name
+          end
+
+          def merge_branch(branch_name, options = {})
+            validate_merge!(branch_name)
+            source_tip = branch_tip(branch_name)
+            current_tip = branch_tip(@current_branch)
+            add_commit(
+              options.merge(
+                is_merge: true,
+                merge_branch: branch_name,
+                parent_ids: [current_tip, source_tip].compact,
+              ),
+            )
+          end
+
+          def cherry_pick(options = {})
+            validate_cherry_pick!(options)
+            add_commit(
+              options.merge(is_cherry_pick: true),
+            )
+          end
+
+          private
+
+          def process_statement(statement)
+            entry = STATEMENT_HANDLERS.find { |key, _| statement.key?(key) }
+            unless entry
+              self.acc_description = State.directive_text(statement[:acc_descr])
+              return
+            end
+
+            send(entry.last, statement.fetch(entry.first))
+          end
+
+          def process_commit(data)
+            options = data.is_a?(Hash) ? extract_options(data[:options]) : {}
+            add_commit(options)
+          end
+
+          def process_branch(data)
+            options = data[:options]
+            order = options.first[:order].to_i if options
+            name = State.unquote(data[:name])
+            add_branch(name, order)
+            checkout_branch(name)
+          end
+
+          def process_checkout(data)
+            checkout_branch(State.unquote(data[:branch]))
+          end
+
+          alias process_switch process_checkout
+
+          def process_merge(data)
+            branch = State.unquote(data[:branch])
+            merge_branch(branch, extract_options(data[:options]))
+          end
+
+          def process_cherry_pick(data)
+            cherry_pick(extract_options(data[:options]))
+          end
+
+          def process_acc_title(data)
+            self.acc_title = State.directive_text(data)
+          end
+
+          def branch_entry(name, info)
+            {
+              name: name,
+              order: info[:order],
+              parent_branch: info[:parent_branch],
+              created_at_commit: info[:created_at],
+            }
+          end
+
+          def find_parents
+            tip = branch_tip(@current_branch)
+            tip ? [tip] : []
+          end
+
+          def branch_tip(name)
+            commit = @commits.reverse.find { |item| item[:branch_name] == name }
+            commit&.fetch(:id) || @branches.fetch(name).fetch(:created_at)
+          end
+
+          def validate_commit_id!(commit_id, options)
+            return unless options[:is_merge]
+            return unless @commits.any? { |item| item[:id] == commit_id }
+
+            raise Parser::ParseError, "Commit id #{commit_id} already exists."
+          end
+
+          def validate_merge!(branch_name)
+            unless @branches.key?(branch_name)
+              raise Parser::ParseError, "Unknown branch: #{branch_name}."
+            end
+            if branch_name == @current_branch
+              raise Parser::ParseError, "Cannot merge a branch into itself."
+            end
+
+            tips = branch_tips(branch_name, @current_branch)
+            return if tips.first && tips.uniq.length == 2
+
+            raise Parser::ParseError,
+                  "Branch #{branch_name} has no new commits to merge."
+          end
+
+          def branch_tips(*names)
+            names.map { |name| branch_tip(name) }
+          end
+
+          def validate_cherry_pick!(options)
+            target = cherry_pick_target!(options[:id])
+
+            parent = options[:cherry_pick_parent]
+            valid_parent = parent && target[:parent_ids].include?(parent)
+            return unless target[:is_merge] && !valid_parent
+
+            raise Parser::ParseError,
+                  "Cherry-picking merge commit #{target[:id]} requires " \
+                  "a valid parent."
+          end
+
+          def cherry_pick_target!(commit_id)
+            @commits.find { |item| item[:id] == commit_id } ||
+              raise(Parser::ParseError,
+                    "Unknown cherry-pick commit: #{commit_id}.")
+          end
+        end
+
+        def self.build(statements, main_branch_name: "main")
+          State.new(main_branch_name).process(statements).to_h
+        end
+
+        # Statement handlers
+        rule(statements: subtree(:stmts)) do
+          GitGraph.build(stmts)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../../diagram/info"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for converting Parslet parse tree to Info diagram model.
+      #
+      # Converts the parse tree output from Grammars::Info into a
+      # fully-formed Diagram::Info object.
+      class Info
+        # Transform parse tree into Info diagram.
+        #
+        # @param tree [Array, Hash] Parslet parse tree
+        # @return [Diagram::Info] the info diagram model
+        def apply(tree)
+          diagram = Diagram::Info.new
+          info_items(tree).each { |item| process_item(diagram, item) }
+          diagram
+        end
+
+        private
+
+        def info_items(tree)
+          items = tree.is_a?(Array) ? tree : [tree]
+          items.grep(Hash)
+        end
+
+        def process_item(diagram, item)
+          if item.key?(:show_info_inline)
+            process_show_info_inline(diagram, item)
+          end
+          process_show_info_body(diagram, item) if item.key?(:show_info_body)
+        end
+
+        def process_show_info_inline(diagram, item)
+          show_info = item[:show_info_inline]
+          return unless show_info
+          return if show_info.to_s.strip.empty?
+
+          # showInfo flag is present inline
+          diagram.show_info = true
+        end
+
+        def process_show_info_body(diagram, item)
+          show_info = item[:show_info_body]
+          return unless show_info
+          return if show_info.to_s.strip.empty?
+
+          # showInfo flag is present in body
+          diagram.show_info = true
+        end
+      end
+    end
+  end
+end