etassia 0.1.0

data/lib/etassia/engine.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require_relative "error/diagram_type_error"
+require_relative "error/pipeline_error"
+require_relative "notation"
+require_relative "notation/mermaid"
+require_relative "theme/completion"
+
+module Etassia
+  # Orchestrates the complete diagram rendering pipeline.
+  #
+  # The Engine class coordinates the parse → transform → layout → render
+  # pipeline for converting diagram source code into SVG output. Choosing the
+  # notation belongs to {Notation.resolve}, and detection and parsing to the
+  # notation itself (see {Notation::Mermaid}); the engine runs what the
+  # notation returns and manages error handling throughout the process.
+  #
+  # @example Render a flowchart
+  #   engine = Etassia::Engine.new
+  #   svg = engine.render("graph TD\nA-->B")
+  #   puts svg
+  #
+  # @example Render with options
+  #   engine = Etassia::Engine.new
+  #   svg = engine.render(source, verbose: true)
+  class Engine
+    # @deprecated Use {Etassia::Notation::Mermaid::DIAGRAM_TYPE_PATTERNS}.
+    DIAGRAM_TYPE_PATTERNS = Notation::Mermaid::DIAGRAM_TYPE_PATTERNS
+
+    # @deprecated Use {Etassia::Notation::Mermaid::DIAGRAM_TYPE_KEYWORDS}.
+    DIAGRAM_TYPE_KEYWORDS = Notation::Mermaid::DIAGRAM_TYPE_KEYWORDS
+
+    attr_reader :verbose, :theme, :logger
+
+    # Creates a new Engine instance.
+    #
+    # @param verbose [Boolean] enable verbose output for debugging
+    # @param theme [String, Symbol, Theme, Hash, nil] theme specification
+    # @param today [Date, nil] reference date for diagrams that need one
+    #   (gantt). Pin it to make rendering reproducible; nil uses the real
+    #   date.
+    # @param notation [Symbol, String, nil] the notation to read sources
+    #   with; nil lets each render pick one from its path and source
+    # @param logger [Logger, nil] destination for diagnostics. A host
+    #   embedding Etassia and reading stdout as pure SVG cannot tolerate log
+    #   lines landing on the same stream, so the default logs to $stderr
+    #   instead; pass one in to redirect or format diagnostics your own way.
+    # @raise [PipelineError] if `notation` is invalid or not registered
+    #
+    # Theme loading parses attacker-supplied YAML, and it happens here,
+    # before `render` is ever called. The exhaustion rescue converts those
+    # VM-level failures into the public pipeline error contract.
+    def initialize(verbose: false, theme: nil, today: nil, logger: nil,
+                   notation: nil)
+      @verbose = verbose
+      @notation_id = registered_id(notation)
+      @theme = load_theme(theme)
+      @today = today
+      @logger = logger || default_logger
+    rescue *EXHAUSTION_ERRORS => e
+      raise PipelineError, "Theme loading failed: #{e.message}"
+    end
+
+    # Renders diagram source code to SVG.
+    #
+    # @param source [String] diagram source code
+    # @param options [Hash] rendering options
+    # @option options [Boolean] :verbose enable verbose output
+    # @option options [String, Symbol, Theme, Hash, nil] :theme theme override
+    # @option options [Date, nil] :today reference date override
+    # @option options [Symbol, String, nil] :notation notation override
+    # @option options [String, nil] :path where the source came from; its
+    #   extension picks the notation when none is given, and its directory
+    #   is where a notation that reads files looks first
+    # @option options [String, nil] :base_dir that directory when the
+    #   source has no file of its own (an inline block in a document)
+    # @option options [Array<String>, String, nil] :include_path further
+    #   directories a notation may read files from
+    # @option options [Symbol] :layout_engine :grid (default) or :elk, which
+    #   lays flowcharts out with elkrb and raises for any other diagram type
+    # @return [String] SVG XML string
+    # @raise [PipelineError] if `notation` is invalid or not registered
+    # @raise [DiagramTypeError] if diagram type cannot be detected
+    # @raise [Parser::ParseError] if the source fails to parse
+    # @raise [Layout::LayoutError] if the diagram fails its own
+    #   validity check
+    # @raise [Renderer::RenderError] if rendering itself fails
+    # @raise [PipelineError] if a stage fails with no error class of its own
+    #
+    # Layer-specific Etassia errors propagate unchanged so the corpus harness
+    # keeps their stage. Exhaustion and notation-plugin failures are wrapped,
+    # without embedding backtraces in messages; Ruby retains each cause for
+    # diagnostics while batch rendering avoids accumulating huge strings.
+    def render(source, options = {})
+      render_pipeline(source, options)
+    rescue Error
+      raise
+    rescue *EXHAUSTION_ERRORS => e
+      raise PipelineError, "Rendering failed: #{e.message}"
+    rescue Notation::PluginFailure => e
+      raise PipelineError, "Rendering failed: #{describe_failure(e)}"
+    end
+
+    private
+
+    def default_logger
+      Logger.new($stderr).tap do |created_logger|
+        created_logger.formatter = proc do |_level, _time, _name, message|
+          "[Etassia::Engine] #{message}\n"
+        end
+      end
+    end
+
+    def render_pipeline(source, options)
+      @verbose = options[:verbose] if options.key?(:verbose)
+      theme, today, layout_engine = render_settings(options)
+      log "Starting render pipeline..."
+      notation = resolve_notation(source, options)
+      parsed = parse_source(notation, source, options)
+      layout_result = transform_diagram(
+        parsed.diagram, parsed.transform, today, theme,
+        **placement_options(parsed, options, layout_engine)
+      )
+      serialize(render_svg(layout_result, parsed.renderer, theme))
+    end
+
+    def placement_options(parsed, options, layout_engine)
+      source_layout = source_layout_engine(parsed, options)
+      if source_layout.nil?
+        return { layout_engine: layout_engine, source_layout: false }
+      end
+
+      { layout_engine: checked_layout_engine(source_layout),
+        source_layout: true }
+    end
+
+    def render_settings(options)
+      theme = options[:theme] ? load_theme(options[:theme]) : @theme
+      today = options.key?(:today) ? options[:today] : @today
+      layout_engine = checked_layout_engine(
+        options.fetch(:layout_engine, :grid),
+      )
+      [theme, today, layout_engine]
+    end
+
+    def resolve_notation(source, options)
+      explicit = case options[:notation]
+                 when nil then @notation_id
+                 else options[:notation]
+                 end
+      Notation.resolve(
+        explicit: explicit,
+        path: options[:path],
+        source: source,
+      )
+    end
+
+    def serialize(document)
+      xml = document.to_xml
+      log "Render complete, #{xml.length} bytes"
+      xml
+    end
+
+    # "Class: message", for an exception whose own #message may raise (an
+    # RSpec::Expectations::MultipleExpectationsNotMetError built without its
+    # aggregator does).
+    def describe_failure(error)
+      "#{error.class}: #{error.message}"
+    rescue Notation::PluginFailure
+      "#{error.class}: <message unavailable>"
+    end
+
+    # A notation declares the keywords it wants and gets only those:
+    # `logger:` (progress lines), `base_dir:` (where the source lives, for a
+    # notation that reads files beside it) and `include_path:` (further
+    # directories such a notation may read). One that declares none is
+    # called with the source alone.
+    def parse_source(notation, source, options)
+      context = {
+        logger: verbose ? logger : nil,
+        base_dir: base_dir_of(options),
+        include_path: options[:include_path],
+      }
+      wanted = notation.method(:parse).parameters.filter_map do |kind, name|
+        name if kind == :key
+      end
+      notation.parse(source, **context.slice(*wanted))
+    end
+
+    # `:base_dir`, else the directory of `:path`.
+    def base_dir_of(options)
+      return options[:base_dir] if options[:base_dir]
+      return unless options[:path]
+
+      File.dirname(File.expand_path(options[:path]))
+    end
+
+    # The registry's key for a validated notation, not the id the plugin
+    # answers later.
+    def registered_id(notation)
+      case notation
+      when nil
+        nil
+      else
+        Notation.fetch(notation)
+        case notation
+        when Symbol then notation
+        else String.instance_method(:to_sym).bind_call(notation)
+        end
+      end
+    end
+
+    # Lays out the diagram model.
+    #
+    # @param diagram [Diagram::Base] diagram model
+    # @param transform_class [Class] layout class
+    # @param today [Date, nil] reference date, or nil for the real date
+    # @param theme [Theme] theme the layout may size text with
+    # @param placement [Hash] `:layout_engine` (:grid or :elk, default :grid)
+    #   and `:source_layout` (true when the source chose the engine)
+    # @return [Layout::Scene, Layout::Legacy] a Scene, or a wrapped graph
+    def transform_diagram(diagram, transform_class, today, theme, **placement)
+      log "Transforming diagram to graph..."
+      layout = transform_class.new
+      choose_placement(layout, **placement)
+      result = layout.call(diagram, theme: theme, today: today)
+      log "Transform complete"
+      result
+    end
+
+    def checked_layout_engine(name)
+      return name if %i[grid elk].include?(name)
+
+      raise PipelineError, "Unknown layout_engine: #{name.inspect}"
+    end
+
+    def source_layout_engine(parsed, options)
+      parsed.layout_engine unless options.key?(:layout_engine)
+    end
+
+    def choose_placement(layout, layout_engine: :grid, source_layout: false)
+      return if layout_engine == :grid
+
+      unless layout.respond_to?(:placement=)
+        raise Layout::LayoutError,
+              "layout_engine :elk is not available for #{layout.class}"
+      end
+      layout.public_send(placement_setter(layout, source_layout), layout_engine)
+    end
+
+    def placement_setter(layout, source_layout)
+      if source_layout && layout.respond_to?(:source_placement=)
+        :source_placement=
+      else
+        :placement=
+      end
+    end
+
+    # Renders the layout result to an SVG document.
+    #
+    # @param layout_result [Object] output produced by the notation's layout
+    #   transform
+    # @param renderer_class [Class] renderer class
+    # @param theme [Theme] theme to use for rendering
+    # @return [Svg::Document] SVG document
+    def render_svg(layout_result, renderer_class, theme)
+      log "Computing layout..."
+      log "Layout complete"
+      log "Rendering to SVG..."
+      renderer = renderer_class.new(theme: theme)
+      svg = renderer.render(layout_result)
+      log "SVG render complete"
+      svg
+    end
+
+    # Loads a theme from various specifications.
+    #
+    # @param theme_spec [String, Symbol, Theme, Hash, nil] theme specification
+    # @return [Theme] loaded theme
+    def load_theme(theme_spec)
+      Theme::Completion.call(resolve_theme_spec(theme_spec))
+    end
+
+    def resolve_theme_spec(theme_spec)
+      return Theme::Registry.get(:default) if theme_spec.nil?
+
+      case theme_spec
+      when String then load_string_theme(theme_spec)
+      when Symbol then resolve_theme_name(theme_spec.to_s)
+      when Theme then theme_spec
+      when Hash then Theme.new(**theme_spec)
+      else Theme::Registry.get(:default)
+      end
+    end
+
+    def load_string_theme(theme_spec)
+      return Theme.load(theme_spec) if File.exist?(theme_spec)
+
+      resolve_theme_name(theme_spec)
+    end
+
+    # Resolves a theme name against the registry, or raises -- an unknown
+    # name used to fall back to the default theme silently (exit 0, wrong
+    # theme drawn). A typo and an intentional `--theme default` looked
+    # identical to the caller.
+    #
+    # @param name [String] the requested theme name
+    # @return [Theme] the matching registered theme
+    # @raise [PipelineError] if no theme is registered under that name
+    def resolve_theme_name(name)
+      Theme::Registry.get(name.to_sym) || raise(
+        PipelineError,
+        "Unknown theme: #{name}. Valid themes: " \
+        "#{Theme::Registry.list.map(&:to_s).sort.join(', ')}",
+      )
+    end
+
+    # Logs a diagnostic message at debug level, gated on @verbose. This
+    # never touches the logger's own `.level` -- an injected logger may be
+    # shared with (or owned by) the host embedding Etassia, and mutating its
+    # level as a side effect of construction/render either corrupts the
+    # host's own filtering or crashes outright for a duck-typed logger that
+    # doesn't implement `level=` (only `debug`/`info`/`warn`, the documented
+    # contract). A plain guard needs neither.
+    #
+    # @param message [String] message to log
+    # @return [void]
+    def log(message)
+      logger.debug(message) if verbose
+    end
+  end
+end

data/lib/etassia/error/diagram_type_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Etassia
+  class Engine
+    # Error raised when diagram type cannot be detected
+    class DiagramTypeError < Etassia::Error; end
+  end
+end

data/lib/etassia/error/layout_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Etassia
+  module Layout
+    # Error raised during layout. A Etassia::Error so Engine#render
+    # can let it propagate unwrapped instead of collapsing it into
+    # PipelineError.
+    class LayoutError < Etassia::Error; end
+  end
+end

data/lib/etassia/error/notation_registration_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Etassia
+  # Raised by {Etassia::Notation.register} when a plugin breaks the notation
+  # contract: a malformed member, a duplicate id, or an extension another
+  # notation already claims.
+  class NotationRegistrationError < Etassia::Error; end
+end

data/lib/etassia/error/parse_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Etassia
+  module Parser
+    # Error raised during parsing. A Etassia::Error so Engine#render can let
+    # it propagate unwrapped instead of collapsing it into PipelineError.
+    class ParseError < Etassia::Error; end
+  end
+end

data/lib/etassia/error/pipeline_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Etassia
+  class Engine
+    # Error raised during pipeline execution
+    class PipelineError < Etassia::Error; end
+  end
+end

data/lib/etassia/error/render_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Etassia
+  module Renderer
+    # Error raised during rendering. A Etassia::Error so Engine#render can
+    # let it propagate unwrapped instead of collapsing it into
+    # PipelineError.
+    class RenderError < Etassia::Error; end
+  end
+end

data/lib/etassia/error/score_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Etassia
+  module Parser
+    # A value the source spelled validly but the diagram type does not
+    # allow, such as a user journey score outside 1..5. Not a ParseError:
+    # the source parsed.
+    class ScoreError < Etassia::Error; end
+  end
+end

data/lib/etassia/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Etassia
+  # Base class for every Etassia::Error subclass across the pipeline (parser,
+  # transform, renderer, engine). Its own file -- like version.rb -- so a
+  # component's base.rb can require_relative it directly and load standalone
+  # (`require "etassia/parser"` etc.) without first loading the whole
+  # lib/etassia.rb require chain.
+  class Error < StandardError; end
+end

data/lib/etassia/error_report.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Etassia
+  # Renders an exception for a `--verbose` reader, following the `cause`
+  # chain the engine deliberately leaves out of its messages.
+  #
+  # `Engine#render` raises `PipelineError` with `e.message` only, never
+  # `e.backtrace`. A real stack overflow's backtrace ran to 1,044,280 bytes
+  # for one measured bomb, and `BatchCommand` keeps every failure's message
+  # for the length of the run, so baking the trace into the string
+  # re-accumulated the very memory that guard exists to bound. Raising
+  # inside the rescue chains the original on as `cause`, so nothing is lost
+  # — it is simply one `.cause` away instead of inside every `#message`.
+  #
+  # Reading it back is this module's job. Without it `--verbose` shows a
+  # trace that starts at the re-raise in `engine.rb` and omits the parser
+  # frames that say what actually went wrong.
+  module ErrorReport
+    # How many frames of a CAUSE's backtrace to print.
+    #
+    # The top-level error's own trace is printed whole, because a wrapper
+    # raised at a known line is short by construction. A cause is not: the
+    # exhaustion path is exactly where a trace runs to six figures of
+    # frames, and `--verbose` must stay readable on the failure it was most
+    # needed for. The innermost frames are the ones that name the fault, so
+    # the head of the trace is the part worth keeping.
+    CAUSE_FRAME_LIMIT = 50
+
+    module_function
+
+    # Every cause below ERROR, deepest last, each with its class, message
+    # and a bounded head of its backtrace.
+    #
+    # @param error [Exception]
+    # @return [String] empty when ERROR has no cause
+    def cause_diagnostics(error)
+      causes(error).map { |cause| one_cause(cause) }.join("\n")
+    end
+
+    # @param error [Exception]
+    # @return [Array<Exception>] the cause chain, nearest first
+    def causes(error)
+      chain = []
+      seen  = [error.object_id]
+      # A `cause` cycle is not reachable through `raise` today, but this
+      # walks user-supplied exceptions and a loop here would hang the CLI
+      # on the one code path whose whole purpose is surviving a bad input.
+      while (error = error.cause) && !seen.include?(error.object_id)
+        seen << error.object_id
+        chain << error
+      end
+      chain
+    end
+
+    # @param cause [Exception]
+    # @return [String]
+    def one_cause(cause)
+      # `backtrace` is nil when the VM fails an allocation before it can
+      # build one, so verbose output must not assume there is a trace.
+      frames = cause.backtrace || []
+      shown  = frames.first(CAUSE_FRAME_LIMIT)
+      omitted = frames.size - shown.size
+
+      lines = ["Caused by: #{cause.class}: #{cause.message}", *shown]
+      lines << "... #{omitted} more frames" if omitted.positive?
+      lines.join("\n")
+    end
+  end
+end

data/lib/etassia/ir/data.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "item"
+require_relative "integrity"
+require_relative "dimension"
+require_relative "series"
+require_relative "data_value"
+
+module Etassia
+  module IR
+    class Data < Item
+      attribute :dimensions, Dimension, collection: true, default: -> { [] }
+      attribute :series, Series, collection: true, default: -> { [] }
+      attribute :values, DataValue, collection: true, default: -> { [] }
+      attribute :items, Item, collection: true, default: -> { [] }
+
+      private
+
+      def semantic_errors
+        super +
+          Integrity.unique_id_errors([self] + members) +
+          Integrity.parent_errors(members) +
+          reference_errors
+      end
+
+      def members
+        dimensions + series + values + items
+      end
+
+      def reference_errors
+        Integrity.reference_errors(
+          values,
+          dimensions: dimensions,
+          series: series,
+        )
+      end
+    end
+  end
+end

data/lib/etassia/ir/data_value.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "item"
+require_relative "scalar"
+
+module Etassia
+  module IR
+    class DataValue < Item
+      attribute :dimension_id, :string
+      attribute :series_id, :string
+      attribute :value, Scalar
+
+      private
+
+      def semantic_errors
+        super + reference_errors + value_errors
+      end
+
+      def reference_errors
+        references = { dimension_id: dimension_id, series_id: series_id }
+        references.filter_map do |name, reference|
+          next unless reference == ""
+
+          validation_error("#{name} must be nonempty when present")
+        end
+      end
+
+      def value_errors
+        return [] if value&.valid?
+
+        [validation_error("value must be a valid Scalar")]
+      end
+    end
+  end
+end

data/lib/etassia/ir/dimension.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "item"
+
+module Etassia
+  module IR
+    class Dimension < Item
+    end
+  end
+end

data/lib/etassia/ir/edge.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "item"
+
+module Etassia
+  module IR
+    class Edge < Item
+      attribute :source_id, :string
+      attribute :target_id, :string
+      attribute :minimum_rank_span, :integer
+
+      private
+
+      def semantic_errors
+        super.concat(missing_id_errors, rank_span_errors)
+      end
+
+      def missing_id_errors
+        { "source_id" => source_id, "target_id" => target_id }
+          .filter_map do |name, value|
+          next unless value.nil? || value.empty?
+
+          validation_error("#{name} must be nonempty")
+        end
+      end
+
+      def rank_span_errors
+        return [] unless minimum_rank_span && !minimum_rank_span.positive?
+
+        [validation_error("minimum_rank_span must be a positive integer")]
+      end
+    end
+  end
+end

data/lib/etassia/ir/graph.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "item"
+require_relative "integrity"
+require_relative "node"
+require_relative "edge"
+
+module Etassia
+  module IR
+    class Graph < Item
+      attribute :nodes, Node, collection: true, default: -> { [] }
+      attribute :edges, Edge, collection: true, default: -> { [] }
+
+      def items
+        nodes + edges
+      end
+
+      private
+
+      def semantic_errors
+        super +
+          Integrity.unique_id_errors([self] + items) +
+          Integrity.parent_errors(items, parents: nodes) +
+          Integrity.endpoint_errors(edges, endpoints: nodes)
+      end
+    end
+  end
+end