etassia 0.1.0

data/lib/etassia/notation.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require_relative "error/notation_registration_error"
+require_relative "error/pipeline_error"
+require_relative "notation/entry"
+require_relative "notation/parsed"
+require_relative "notation/plugin_failure"
+
+module Etassia
+  # The registry of diagram notations. A notation is any object answering:
+  #
+  # - `id`: a lowercase Symbol, `/\A[a-z][a-z0-9_]*\z/`
+  # - `extensions`: a frozen Array of lowercase dotted Strings, may be empty
+  # - `claims?(source)`: true or false; never raises for any String
+  # - `parse(source)`: returns a {Parsed}; an optional `logger:` keyword,
+  #   declared by that name (`**options` does not count), receives the
+  #   engine's progress lines under `verbose`
+  # - `types`: an Array of Symbols
+  #
+  # Loading a file that calls {register} is all a consumer does to add one.
+  module Notation
+    ID_PATTERN = /\A[a-z][a-z0-9_]*\z/
+    EXTENSION_PATTERN = /\A\.[a-z0-9_+-]+\z/
+    DEFAULT_ID = :mermaid
+    # The members `register` checks after `id`, in order, each by the
+    # private method named here. `register` has no other plugin access.
+    MEMBER_CHECKS = {
+      extensions: :validated_extensions,
+      claims?: :validated_claims,
+      parse: :validated_parse,
+      types: :validate_types,
+    }.freeze
+    private_constant :EXTENSION_PATTERN, :DEFAULT_ID, :MEMBER_CHECKS,
+                     :Entry
+
+    class << self
+      # Registers a notation, validating everything before recording
+      # anything. `claims?` and `parse` take exactly one positional argument.
+      # Register at load time: the registry is not thread-safe.
+      #
+      # A plugin is trusted code: this refuses honest mistakes, not one that
+      # overrides core methods (`method`, `is_a?`) to misreport itself.
+      #
+      # @param plugin [#id, #extensions, #claims?, #parse, #types]
+      # @return [void]
+      # @raise [NotationRegistrationError] naming the first broken member,
+      #   including one whose reader raises
+      def register(plugin)
+        member = :id
+        id = validated_id(plugin)
+        checked = MEMBER_CHECKS.to_h do |name, check|
+          member = name
+          [name, send(check, plugin, id)]
+        end
+        record(plugin, id, checked[:extensions])
+      rescue NotationRegistrationError then raise
+      rescue PluginFailure
+        raise malformed(member, id)
+      end
+
+      # @param id [Symbol, String]
+      # @return [#parse] the registered notation
+      # @raise [Engine::PipelineError] when `id` is not a Symbol or String,
+      #   or names no registered notation
+      def fetch(id)
+        entry = lookup(id)
+        return entry.plugin if entry
+
+        raise Engine::PipelineError,
+              "Unknown notation: #{printable(id)}. " \
+              "Valid notations: #{ids.sort.join(', ')}"
+      end
+
+      # @return [Array<Symbol>] registered ids, in registration order
+      def ids
+        entries.keys
+      end
+
+      # @return [Array] registered notations, in registration order
+      def plugins
+        entries.values.map(&:plugin)
+      end
+
+      # @return [Array<String>] every registered extension
+      def extensions
+        entries.values.flat_map(&:extensions)
+      end
+
+      # @param extension [String] lowercase, dotted
+      # @return [Object, nil] the notation that claims it
+      def for_extension(extension)
+        entries.each_value do |entry|
+          return entry.plugin if entry.extensions.include?(extension)
+        end
+        nil
+      end
+
+      # Picks the notation for one render. The first signal that yields one
+      # wins: the explicit id, then the path's extension, then the first
+      # notation (in registration order) that claims the source, then Mermaid.
+      #
+      # @param explicit [Symbol, String, nil]
+      # @param path [String, nil]
+      # @param source [String]
+      # @return [#parse]
+      # @raise [Engine::PipelineError] for an invalid or unknown explicit id
+      def resolve(explicit:, path:, source:)
+        case explicit
+        when nil
+          for_extension(extension_of(path)) ||
+            plugins.find { |plugin| plugin.claims?(source) } ||
+            fetch(DEFAULT_ID)
+        else
+          fetch(explicit)
+        end
+      end
+
+      private
+
+      def entries
+        @entries ||= {}
+      end
+
+      def record(plugin, id, declared)
+        entries[id] = Entry.new(plugin, declared)
+        nil
+      end
+
+      def malformed(member, id)
+        owner = id ? "Notation #{id}" : "Notation"
+        NotationRegistrationError.new("#{owner}: #{member} is malformed")
+      end
+
+      # A path is a hint, never a reason to fail: one that cannot name a
+      # file (NUL byte, invalid or non-ASCII-compatible encoding) has no
+      # extension, and the source decides.
+      def extension_of(path)
+        name = String === path ? String.new(path) : path.to_s
+        return "" unless name.encoding.ascii_compatible? && name.valid_encoding?
+        return "" if name.include?("\0")
+
+        File.extname(name).downcase(:ascii)
+      end
+
+      def takes_no_arguments?(plugin, name)
+        parameter_kinds(plugin, name).slice(:req, :keyreq).empty?
+      end
+
+      # Exactly one positional parameter; optional keywords are fine.
+      def one_positional?(plugin, name)
+        parameter_kinds(plugin, name)
+          .slice(:req, :opt, :rest, :keyreq) == { req: 1 }
+      end
+
+      def parameter_kinds(plugin, name)
+        plugin.method(name).parameters.map(&:first).tally
+      end
+
+      def printable(id)
+        utf8(String === id ? String.new(id) : id.to_s)
+      end
+
+      def utf8(string)
+        string.encode("UTF-8", invalid: :replace, undef: :replace).scrub
+      rescue Encoding::ConverterNotFoundError
+        string.b.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      def lookup(id)
+        case id
+        when Symbol then entries[id]
+        when String then entries[string_id(id)]
+        else
+          raise Engine::PipelineError,
+                "Invalid notation: #{safe_inspect(id)}. " \
+                "Notation must be a Symbol or String"
+        end
+      end
+
+      def string_id(id)
+        return unless String.instance_method(:valid_encoding?).bind_call(id)
+
+        String.instance_method(:to_sym).bind_call(id)
+      end
+
+      def safe_inspect(value)
+        utf8(String.new(value.inspect))
+      rescue PluginFailure
+        "<uninspectable>"
+      end
+
+      def validated_id(plugin)
+        id = member(plugin, :id)
+        unless Symbol === id && matches?(id.to_s, ID_PATTERN)
+          raise NotationRegistrationError,
+                "Notation id must be a lowercase Symbol matching " \
+                "#{ID_PATTERN.inspect}, got #{id.inspect}"
+        end
+        return id unless entries.key?(id)
+
+        raise NotationRegistrationError, "Notation #{id} is already registered"
+      end
+
+      def validated_extensions(plugin, id)
+        declared = member(plugin, :extensions, id)
+        check_extension_shape!(declared, id)
+        snapshot = declared.map { |ext| String.new(ext).freeze }.freeze
+        check_extensions_free!(snapshot, id)
+        snapshot
+      end
+
+      def check_extension_shape!(declared, id)
+        return if Array === declared && declared.frozen? &&
+          declared.all? { |ext| extension?(ext) }
+
+        raise NotationRegistrationError,
+              "Notation #{id}: extensions must be a frozen Array of " \
+              "lowercase dotted Strings, got #{declared.inspect}"
+      end
+
+      def extension?(ext)
+        String === ext && matches?(String.new(ext), EXTENSION_PATTERN)
+      end
+
+      # Matching raises on a broken or non-ASCII-compatible string; both are
+      # plain mismatches here.
+      def matches?(string, pattern)
+        string.encoding.ascii_compatible? && string.valid_encoding? &&
+          string.match?(pattern)
+      end
+
+      def check_extensions_free!(declared, id)
+        taken = declared.find do |ext|
+          extensions.include?(ext) || declared.count(ext) > 1
+        end
+        return unless taken
+
+        raise NotationRegistrationError,
+              "Notation #{id}: extension #{taken} is already claimed"
+      end
+
+      def validated_claims(plugin, id)
+        require_one_positional(plugin, :claims?, id)
+      end
+
+      def validated_parse(plugin, id)
+        require_one_positional(plugin, :parse, id)
+      end
+
+      def validate_types(plugin, id)
+        types = member(plugin, :types, id)
+        return if Array === types && types.all?(Symbol)
+
+        raise NotationRegistrationError,
+              "Notation #{id}: types must be an Array of Symbols, " \
+              "got #{types.inspect}"
+      end
+
+      def member(plugin, name, id = nil)
+        owner = id ? "Notation #{id}" : "Notation"
+        unless public_member?(plugin, name)
+          raise NotationRegistrationError, "#{owner} must respond to #{name}"
+        end
+        return plugin.public_send(name) if takes_no_arguments?(plugin, name)
+
+        raise NotationRegistrationError,
+              "#{owner}: #{name} must take no arguments"
+      end
+
+      def require_one_positional(plugin, name, id)
+        unless public_member?(plugin, name)
+          raise NotationRegistrationError,
+                "Notation #{id} must respond to #{name}"
+        end
+        return if one_positional?(plugin, name)
+
+        raise NotationRegistrationError,
+              "Notation #{id}: #{name} must take one positional argument"
+      end
+
+      # Object's own respond_to?, so a plugin cannot answer for itself; a
+      # BasicObject or a raising respond_to_missing? counts as "no".
+      def public_member?(plugin, name)
+        Object.instance_method(:respond_to?).bind_call(plugin, name)
+      rescue StandardError then false
+      end
+    end
+  end
+end

data/lib/etassia/parser/architecture.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/architecture"
+require_relative "builders/architecture"
+require_relative "native/builders/architecture"
+
+module Etassia
+  module Parser
+    # Parser for architecture diagrams
+    class Architecture < Base
+      grammar Grammars::Architecture
+      builder Builders::Architecture
+      native :architecture, builder: Native::Builders::Architecture
+
+      # Stripped before parsing. The grammar tolerates leading and trailing
+      # whitespace, but String#strip also removes ,  and 
+      # grammar does not, so dropping it changes which inputs parse. Error
+      # positions are therefore relative to the stripped source.
+      def parse(input)
+        super(input.strip)
+      end
+    end
+  end
+end

data/lib/etassia/parser/atoms/delimited_run.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "parslet"
+require_relative "greedy_run"
+
+module Etassia
+  module Parser
+    module Atoms
+      # Matches `delimiter` once, then one-or-more repetitions of (a run
+      # of `segment_class`, then `delimiter` again) -- e.g. Mermaid's ER
+      # `~T~` core, `~(?:[^~<terminator>]*~)+`. JS's `.*` is greedy, so
+      # this matches through to the LAST delimiter reachable, not the
+      # first. Accumulate segments with `<<`, never `.repeat`/`Slice#+`
+      # (O(n^2)); call `GreedyRun.scan` per segment. Every call restarts
+      # its doubling probe at the small initial size, so a short segment
+      # costs about its own length -- that reset is what keeps the whole
+      # match linear.
+      class DelimitedRun < Parslet::Atoms::Base
+        def initialize(delimiter, segment_class)
+          super()
+          if delimiter.length != 1
+            message = "delimiter must be one character, got "
+            message += delimiter.inspect
+            raise ArgumentError, message
+          end
+
+          @delimiter = delimiter
+          @segment_re = GreedyRun.anchored(segment_class)
+        end
+
+        def try(source, context, _consume_all)
+          start = source.bytepos
+          anchor = source.consume(0)
+          return opening_error(source, context, start) unless opening?(source)
+
+          buffer, segments = consume_segments(source)
+          return segment_error(source, context, start) if segments.zero?
+
+          succ(Parslet::Slice.new(anchor.position, buffer, anchor.line_cache))
+        end
+
+        def opening?(source)
+          source.consume(1).to_s == @delimiter
+        end
+
+        def opening_error(source, context, start)
+          source.bytepos = start
+          context.err(self, source, "Expected #{@delimiter.inspect}")
+        end
+
+        def consume_segments(source)
+          buffer = +@delimiter
+          segments = 0
+          while (run = consume_segment(source))
+            buffer << run << @delimiter
+            segments += 1
+          end
+          [buffer, segments]
+        end
+
+        def consume_segment(source)
+          before = source.bytepos
+          run = GreedyRun.scan(source, @segment_re)
+          return run if source.consume(1).to_s == @delimiter
+
+          source.bytepos = before
+          nil
+        end
+
+        def segment_error(source, context, start)
+          source.bytepos = start
+          message = "Expected at least one #{@delimiter.inspect}-closed run"
+          context.err(self, source, message)
+        end
+
+        def to_s_inner(_prec)
+          "#{@delimiter}(?:#{@segment_re.inspect}#{@delimiter})+"
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/atoms/greedy_run.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Etassia
+  module Parser
+    module Atoms
+      # Matches a run of `char_class` (e.g. `[^\]]`) in bounded native
+      # regex scans, avoiding Parslet's default `match(char_class).repeat`
+      # (applies its atom once per character -- DoS shape on a long run).
+      #
+      # Consumes CHARACTER-count chunks and matches each with Ruby's own
+      # (character-correct) `Regexp`, never `Parslet::Source#matches?`
+      # (returns the match length in BYTES; `Source#consume(n)` takes a
+      # CHARACTER count - mixing the two over-consumes on a multibyte body,
+      # e.g. the text of kanban's `root[café]`).
+      class GreedyRun < Parslet::Atoms::Base
+        # First chunk size tried; doubles each round up to CHUNK. A short
+        # run (the common case) then costs about its own length instead of
+        # a fixed CHUNK per call.
+        INITIAL_PROBE = 64
+        private_constant :INITIAL_PROBE
+
+        # `Parslet::Source#consume(n)` builds a `/(.|$){n}/` regexp to pull
+        # n characters at once, and Ruby's regexp engine refuses a repeat
+        # count above 100_000 (`RegexpError: too big number for repeat
+        # range`). Chunks stay well under that ceiling.
+        CHUNK = 50_000
+        private_constant :CHUNK
+
+        # `min: 1` (default) requires at least one matching character
+        # (`char_class+`); `min: 0` allows an empty match (`char_class*`).
+        def initialize(char_class, min: 1)
+          super()
+          @char_class = char_class
+          @min = min
+          @anchored = self.class.anchored(char_class)
+        end
+
+        def try(source, context, _consume_all)
+          origin = source.consume(0)
+          matched = self.class.scan(source, @anchored)
+
+          message = "Expected at least one matching character"
+          empty = @min.positive? && matched.empty?
+          return context.err(self, source, message) if empty
+
+          succ(Parslet::Slice.new(origin.position, matched, origin.line_cache))
+        end
+
+        # The `\A(?:class)*` regexp that `scan` expects, for a Parslet-style
+        # character class string such as `[^~\n]`.
+        def self.anchored(char_class)
+          Regexp.new("\\A(?:#{char_class})*", Regexp::MULTILINE)
+        end
+
+        # Scans `anchored` (an `\A(?:...)* ` regex) against `source` from
+        # its current position, joining the parts ONCE at the end (never
+        # per chunk -- that would make an attacker-sized body quadratic
+        # again). Shared with `DelimitedRun`, which calls this once per
+        # delimited segment with its own segment regex.
+        def self.scan(source, anchored)
+          buffer = +""
+          probe = INITIAL_PROBE
+
+          loop do
+            break if source.chars_left.zero?
+
+            matched, complete = scan_chunk(source, anchored, probe)
+            buffer << matched
+            break unless complete
+
+            probe = [probe * 2, CHUNK].min
+          end
+
+          buffer
+        end
+
+        # A fixed-UTF-8 regex can reject a binary chunk even when its leading
+        # ASCII run matches. Retry against that prefix, then restore any bytes
+        # consumed beyond the match.
+        def self.scan_chunk(source, anchored, probe)
+          size = [source.chars_left, probe].min
+          chunk = source.consume(size).to_s
+          matched = anchored_match(anchored, chunk)
+          excess = chunk.bytesize - matched.bytesize
+          source.bytepos -= excess
+          [matched, excess.zero?]
+        end
+
+        def self.anchored_match(anchored, chunk)
+          anchored.match(chunk)[0]
+        rescue Encoding::CompatibilityError
+          anchored.match(ascii_prefix(chunk))[0]
+        end
+
+        # The bytes of `chunk_str` before its first byte >= 0x80, safe to
+        # match against a fixed-UTF-8 `anchored` because every one of them
+        # is also valid UTF-8. `chunk_str` always carries an ASCII-compatible
+        # encoding here: it comes from a `Parslet::Source`, and
+        # `Source#initialize` itself already rejects any encoding that
+        # isn't (`LineCache#scan_for_line_endings` matching a `US-ASCII`
+        # `/\n/` against it) before this method ever runs.
+        def self.ascii_prefix(chunk_str)
+          high_byte = chunk_str.each_byte.find_index { |byte| byte >= 0x80 }
+          high_byte ? chunk_str.byteslice(0, high_byte) : chunk_str
+        end
+        private_class_method :ascii_prefix
+
+        def to_s_inner(_prec)
+          @anchored.inspect
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/atoms/joined.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Etassia
+  module Parser
+    module Atoms
+      # Matches `inner` and returns everything it consumed as ONE slice.
+      # Parslet joins a repetition of plain slices with `Slice#+`, which
+      # copies the whole string built so far on every step: a body of
+      # n short lines costs O(n^2). Here the pieces are appended to one
+      # buffer instead. `inner` must not capture (`.as`): a named result has
+      # no text to join, so it raises rather than return a shorter string.
+      class Joined < Parslet::Atoms::Base
+        def initialize(inner)
+          super()
+          @inner = inner
+        end
+
+        def try(source, context, consume_all)
+          anchor = source.consume(0)
+          success, value = @inner.apply(source, context, consume_all)
+          return [success, value] unless success
+
+          buffer = +""
+          append(value, buffer)
+          succ(Parslet::Slice.new(anchor.position, buffer, anchor.line_cache))
+        end
+
+        def to_s_inner(prec)
+          @inner.to_s(prec)
+        end
+
+        private
+
+        def append(value, buffer)
+          case value
+          when Array then value.each { |piece| append(piece, buffer) }
+          when Parslet::Slice, String then buffer << value.to_s
+          when Hash
+            raise ArgumentError, "cannot join a captured #{value.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/atoms/trimmed_run.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "greedy_run"
+
+module Etassia
+  module Parser
+    module Atoms
+      # Matches a run of `broad_class` (Kleene star, via `GreedyRun` --
+      # exact across chunk boundaries because a pure character-class-star
+      # is position-independent), then un-consumes trailing characters
+      # matching `trim_class`, giving them back to the source.
+      #
+      # This reproduces a backreference-free version of Ruby/JS's own
+      # backtracking for `\w([-.\/\w]*[-\w])?`: matching the whole greedy
+      # run and then trimming trailing non-`trim_class` characters off
+      # the end is equivalent to backtracking the greedy run one
+      # character at a time until the required trailing char matches.
+      class TrimmedRun < Parslet::Atoms::Base
+        def initialize(broad_class, trim_class)
+          super()
+          @run = GreedyRun.new(broad_class, min: 0)
+          @trim_re = /(?:#{trim_class})*\z/
+        end
+
+        def try(source, context, _consume_all)
+          # `@run` is `GreedyRun.new(broad_class, min: 0)` -- a Kleene star
+          # matches zero or more, so it can never fail; there is no
+          # failure branch to handle here.
+          result = @run.apply(source, context, false).last
+          kept, trimmed = trim_match(result.to_s)
+          source.bytepos -= trimmed.bytesize
+          succ(Parslet::Slice.new(result.position, kept, result.line_cache))
+        end
+
+        def trim_match(matched)
+          trimmed = matched[@trim_re]
+          kept = matched[0...(matched.length - trimmed.length)]
+          [kept, trimmed]
+        end
+
+        def to_s_inner(_prec)
+          "#{@run.inspect}(trim: #{@trim_re.inspect})"
+        end
+      end
+    end
+  end
+end