markdown_composer 0.7.0

data/lib/markdown_composer/plan.rb

@@ -0,0 +1,436 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  class Plan
+    attr_reader :config, :diagnostics
+
+    def self.invalid(code, message)
+      plan = new({})
+      plan.diagnostics.error(code, message)
+      plan
+    end
+
+    def self.from_rows(row_hashes)
+      new("compose" => Array(row_hashes).map { |row| normalize_hash(row) })
+    end
+
+    def self.normalize_hash(value)
+      value.to_h.transform_keys { |key| key.to_s.downcase.tr(" ", "_") }
+    end
+
+    def initialize(config)
+      @diagnostics = Diagnostics.new
+      @config = normalize(config || {})
+    end
+
+    def version
+      config.fetch("version", 1)
+    end
+
+    def output
+      config.fetch("output", "markdown").to_s
+    end
+
+    def steps
+      Array(compose_config).map { |step| normalize_step(step) }
+    end
+
+    def transforms
+      Array(transform_config).map.with_index { |transform, index| normalize_transform(transform, path: "transform[#{index}]") }
+    end
+
+    def to_h
+      canonical = config.reject { |key, _value| %w[steps transforms compose transform].include?(key) }
+      canonical.merge("compose" => steps, "transform" => transforms, "output" => output)
+    end
+
+    private
+
+    def compose_config
+      config.key?("compose") ? config["compose"] : config["steps"]
+    end
+
+    def transform_config
+      config.key?("transform") ? config["transform"] : config["transforms"]
+    end
+
+    def normalize(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, child), hash| hash[key.to_s] = normalize(child) }
+      when Array
+        value.map { |child| normalize(child) }
+      else
+        value
+      end
+    end
+
+    def normalize_step(step)
+      step = normalize(step)
+      step["source"] = normalize_source_ref(step["source"])
+      step["select"] = normalize_selector(step["select"] || step["selector"] || { "type" => "all" }, :select)
+      step["include"] = normalize_include(step["include"])
+      step["action"] = normalize_action(step["action"] || "set")
+      step["target"] = normalize_target(step["target"]) if step.key?("target")
+      step["transforms"] = normalize_row_transforms(step["transforms"]) if step.key?("transforms")
+      step
+    end
+
+    def normalize_transform(transform, path: nil)
+      transform = normalize(transform)
+      transform["scope"] = normalize_selector(transform["scope"] || { "type" => "output" }, :scope)
+      transform["transform"] = normalize_token(transform["transform"], :transform)
+      transform["options"] = normalize_options(transform["options"] || {}, path: path && "#{path}.options")
+      transform
+    end
+
+    def normalize_source_ref(source)
+      source = { "type" => "current" } if source.nil?
+      source = { "type" => source } if source.is_a?(String) || source.is_a?(Symbol)
+      source = normalize(source)
+      type = Registries.default.sources.normalise(source["type"] || "current") || source["type"].to_s
+      source.merge("type" => type)
+    end
+
+    def normalize_action(action)
+      Registries.default.actions.normalise(action.to_s.tr(" ", "_").downcase) || action.to_s
+    end
+
+    def normalize_token(token, consumer)
+      registry = consumer == :transform ? Registries.default.transforms : Registries.default.unit_tokens
+      registry.normalise(token.to_s) || token.to_s
+    end
+
+    def normalize_selector(selector, consumer)
+      return parse_selector(selector, consumer) if selector.is_a?(String)
+
+      selector = normalize(selector || {})
+      if selector["types"]
+        selector["types"] = Array(selector["types"]).map { |type| normalize_token(type, consumer) }
+      else
+        selector["type"] = normalize_token(selector["type"] || "all", consumer)
+      end
+      selector["take"] = normalize_take(selector["take"]) if selector.key?("take")
+      selector["where"] = normalize_where(selector["where"]) if selector.key?("where")
+      selector["include"] = normalize_include(selector["include"]) if selector.key?("include")
+      selector
+    end
+
+    def normalize_include(include_config)
+      include_config = [ { "type" => "all" } ] if include_config.nil? || include_config == ""
+      include_config = [ include_config ] unless include_config.is_a?(Array)
+      include_config.flat_map { |item| normalize_include_item(item) }
+    end
+
+    def normalize_include_item(item)
+      return parse_data_path(item) if item.is_a?(String) && data_path_syntax?(item)
+      return parse_include(item) if item.is_a?(String)
+
+      item = normalize(item)
+      if item.key?("exclude")
+        excluded = normalize_include_item(item["exclude"]).first
+        return [ { "exclude" => excluded } ]
+      end
+
+      item["type"] = normalize_token(item["type"] || "all", :include)
+      item["take"] = normalize_take(item["take"]) if item.key?("take")
+      item["where"] = normalize_where(item["where"]) if item.key?("where")
+      item["include"] = normalize_include(item["include"]) if item.key?("include")
+      [ item ]
+    end
+
+    def normalize_target(target)
+      return parse_target(target) if target.is_a?(String)
+
+      target = normalize(target || {})
+      target["position"] = normalize_target_position(target["position"]) if target["position"]
+      if target["type"].to_s.match?(/\Ain[_ ]place\z/i)
+        target["position"] = normalize_target_position(target.delete("type"))
+      end
+      target["type"] = normalize_token(target["type"], :target) if target["type"]
+      target["take"] = normalize_take(target["take"]) if target.key?("take")
+      target["where"] = normalize_where(target["where"]) if target.key?("where")
+      target["start"] = normalize_target(target["start"]) if target["start"]
+      target["end"] = normalize_target(target["end"]) if target["end"]
+      target
+    end
+
+    def normalize_options(options, path: nil)
+      options = parse_options(options, path: path) if options.is_a?(String)
+      options = normalize(options)
+      unless options.respond_to?(:transform_values)
+        diagnostics.error(
+          "transform.options_syntax",
+          "Options must be a readable options string or object",
+          path: path
+        )
+        return {}
+      end
+
+      options.transform_values do |value|
+        case value
+        when Array
+          value.map { |item| normalize_option_value(item) }
+        else
+          normalize_option_value(value)
+        end
+      end
+        .tap do |hash|
+          hash["target"] = normalize_target(hash["target"]) if hash["target"].is_a?(String) || hash["target"].is_a?(Hash)
+        end
+    end
+
+    def parse_options(string, path: nil)
+      split_option_parts(string, ";", path: path).each_with_object({}) do |part, hash|
+        key, value = split_option_pair(part)
+        hash[key] = parse_option_value(key, value) unless key.empty?
+      end
+    end
+
+    def split_option_parts(text, separator, path: nil)
+      parts = []
+      current = +""
+      depth = 0
+      bracket_depth = 0
+      brace_depth = 0
+      quote = nil
+      chars = text.to_s.each_char.to_a
+
+      chars.each do |char|
+        quote = next_quote_state(quote, char)
+        if quote.nil?
+          depth += 1 if char == "("
+          depth -= 1 if char == ")"
+          bracket_depth += 1 if char == "["
+          bracket_depth -= 1 if char == "]"
+          brace_depth += 1 if char == "{"
+          brace_depth -= 1 if char == "}"
+        end
+
+        if char == separator && quote.nil? && depth.zero? && bracket_depth.zero? && brace_depth.zero?
+          parts << current.strip unless current.strip.empty?
+          current = +""
+        else
+          current << char
+        end
+      end
+
+      diagnostics.error("transform.options_syntax", "Missing closing #{quote} quote in options", path: path) if quote
+      parts << current.strip unless current.strip.empty?
+      parts
+    end
+
+    def split_option_pair(part)
+      text = part.to_s.strip
+      index = top_level_separator_index(text, ":")
+      return [ text.downcase.tr(" ", "_"), true ] unless index
+
+      [
+        text[0...index].strip.downcase.tr(" ", "_"),
+        text[(index + 1)..].to_s.strip
+      ]
+    end
+
+    def parse_option_value(key, value)
+      text = value.to_s.strip
+      return "" if text.empty?
+      return unquote(text) if quoted?(text)
+      return true if text == "true"
+      return false if text == "false"
+      return nil if text == "null" || text == "nil"
+      return text.to_i if text.match?(/\A-?\d+\z/)
+
+      if key == "levels" && text.include?(",")
+        return split_include_parts(text, ",").map { |item| parse_option_value(key, item) }
+      end
+
+      text
+    end
+
+    def top_level_separator_index(text, separator)
+      depth = 0
+      bracket_depth = 0
+      brace_depth = 0
+      quote = nil
+      text.to_s.each_char.with_index do |char, index|
+        quote = next_quote_state(quote, char)
+        if quote.nil?
+          depth += 1 if char == "("
+          depth -= 1 if char == ")"
+          bracket_depth += 1 if char == "["
+          bracket_depth -= 1 if char == "]"
+          brace_depth += 1 if char == "{"
+          brace_depth -= 1 if char == "}"
+        end
+
+        return index if char == separator && depth.zero? && bracket_depth.zero? && brace_depth.zero? && quote.nil?
+      end
+      nil
+    end
+
+    def quoted?(value)
+      text = value.to_s
+      (text.start_with?('"') && text.end_with?('"')) || (text.start_with?("'") && text.end_with?("'"))
+    end
+
+    def unquote(value)
+      value.to_s[1..-2]
+    end
+
+    def normalize_option_value(value)
+      token = Registries.default.unit_tokens.normalise(value.to_s)
+      token || value
+    end
+
+    def normalize_take(take)
+      return Take.parse(take) if take.is_a?(String) || take.is_a?(Symbol)
+
+      take = normalize(take || {})
+      take["position"] = Array(take["position"]).map(&:to_i) if take.key?("position")
+      take
+    end
+
+    def normalize_where(where)
+      Where.normalize(where)
+    end
+
+    def parse_selector(string, consumer)
+      text = string.strip
+      nested = nil
+      if text =~ /\{(.+)\}\s*\z/
+        nested = Regexp.last_match(1)
+        text = text.sub(/\{.+\}\s*\z/, "").strip
+      end
+
+      where = nil
+      if text =~ /\s+where\s+(.+)\z/i
+        where = Regexp.last_match(1).strip
+        text = text.sub(/\s+where\s+.+\z/i, "").strip
+      end
+
+      take = nil
+      if text =~ /\[(.+)\]\s*\z/
+        take = Regexp.last_match(1)
+        text = text.sub(/\[(.+)\]\s*\z/, "").strip
+      end
+
+      if text.include?(",")
+        selector = { "types" => text.split(",").map { |part| normalize_token(part.strip, consumer) } }
+      else
+        selector = { "type" => normalize_token(text, consumer) }
+      end
+      selector["take"] = normalize_take(take) if take
+      selector["where"] = normalize_where(where) if where
+      selector["include"] = parse_include(nested, separator: ";") if nested
+      selector
+    end
+
+    def parse_include(string, separator: ",")
+      parts = split_include_parts(string, separator)
+      parts.flat_map do |part|
+        if data_path_syntax?(part)
+          [ parse_data_path(part) ]
+        elsif part =~ /\A(.+)\s+except\s+(.+)\z/i
+          [ normalize_selector(Regexp.last_match(1), :include), { "exclude" => normalize_selector(Regexp.last_match(2), :include) } ]
+        else
+          [ normalize_selector(part, :include) ]
+        end
+      end
+    end
+
+    def parse_target(string)
+      text = string.strip
+      return { "position" => "output" } if text.match?(/\A(?:whole[_ ]output|output)\z/i)
+      return { "position" => "start" } if text.match?(/\Astart\z/i)
+      return { "position" => "end" } if text.match?(/\Aend\z/i)
+      return { "position" => "in_place" } if text.match?(/\Ain[_ ]place\z/i)
+
+      if text =~ /\Abefore\s+(.+)\z/i
+        return parse_selector(Regexp.last_match(1), :target).merge("placement" => "before")
+      end
+      if text =~ /\Aafter\s+(.+)\z/i
+        return parse_selector(Regexp.last_match(1), :target).merge("placement" => "after")
+      end
+      if text =~ /\Abetween\s+(.+)\s+and\s+(.+)\z/i
+        return {
+          "placement" => "between",
+          "start" => parse_selector(Regexp.last_match(1), :target),
+          "end" => parse_selector(Regexp.last_match(2), :target)
+        }
+      end
+
+      parse_selector(text, :target)
+    end
+
+    def normalize_target_position(position)
+      text = position.to_s.strip.downcase.tr(" ", "_")
+      return "output" if text == "whole_output"
+      return "in_place" if text == "in_place"
+
+      text
+    end
+
+    def normalize_row_transforms(transforms)
+      transforms = normalize(transforms)
+      items = transforms.is_a?(Array) ? transforms : [ transforms ]
+      items.map { |transform| normalize_row_transform(transform) }
+    end
+
+    def normalize_row_transform(transform)
+      raw_transform = normalize(transform)
+      scope_missing = !raw_transform.key?("scope")
+      normalized = normalize_transform(raw_transform)
+      normalized["_scope_missing"] = true if scope_missing
+      normalized
+    end
+
+    def data_path_syntax?(text)
+      text.to_s.strip.match?(/\Adata_path\((["']).*\1\)\z/)
+    end
+
+    def parse_data_path(text)
+      if text.to_s.strip =~ /\Adata_path\((["'])(.*)\1\)\z/
+        { "type" => "data_path", "path" => Regexp.last_match(2) }
+      else
+        { "type" => "data_path", "path" => "" }
+      end
+    end
+
+    def split_include_parts(text, separator)
+      depth = 0
+      bracket_depth = 0
+      brace_depth = 0
+      quote = nil
+      current = +""
+      parts = []
+      text.to_s.each_char do |char|
+        quote = next_quote_state(quote, char)
+        if quote.nil?
+          depth += 1 if char == "("
+          depth -= 1 if char == ")"
+          bracket_depth += 1 if char == "["
+          bracket_depth -= 1 if char == "]"
+          brace_depth += 1 if char == "{"
+          brace_depth -= 1 if char == "}"
+        end
+
+        if char == separator && depth.zero? && bracket_depth.zero? && brace_depth.zero? && quote.nil?
+          parts << current.strip unless current.strip.empty?
+          current = +""
+        else
+          current << char
+        end
+      end
+      parts << current.strip unless current.strip.empty?
+      parts
+    end
+
+    def next_quote_state(quote, char)
+      return quote unless %w[" '].include?(char)
+      return nil if quote == char
+      return char if quote.nil?
+
+      quote
+    end
+  end
+end

data/lib/markdown_composer/plan_builder.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  class PlanBuilder
+    def initialize
+      @rows = []
+      @transforms = []
+      @current = {}
+      @output = nil
+    end
+
+    def from(source)
+      @current["source"] = source
+    end
+
+    def select(selector)
+      @current["select"] = selector
+    end
+
+    def include(*items)
+      existing = Array(@current["include"])
+      @current["include"] = existing.concat(items.flatten).compact
+    end
+
+    def target(target)
+      @current["target"] = target
+    end
+
+    def output(format)
+      @output = format.to_s
+    end
+
+    def set(target = nil)
+      finish("set", target)
+    end
+
+    def append(target = nil)
+      finish("append", target)
+    end
+
+    def prepend(target = nil)
+      finish("prepend", target)
+    end
+
+    def insert_before(target)
+      finish("insert_before", target)
+    end
+
+    def insert_after(target)
+      finish("insert_after", target)
+    end
+
+    def insert_between(target)
+      finish("insert_between", target)
+    end
+
+    def replace(target)
+      finish("replace", target)
+    end
+
+    def copy(target)
+      finish("copy", target)
+    end
+
+    def move(target)
+      finish("move", target)
+    end
+
+    def modify(target = nil, transforms: nil)
+      @current["transforms"] = Array(transforms) if transforms
+      finish("modify", target)
+    end
+
+    def remove_buffer_target(target = nil)
+      target ||= @current["select"]
+      finish("remove_buffer_target", target)
+    end
+
+    def transform_buffer_target(target = nil, transforms: nil)
+      @current["transforms"] = Array(transforms) if transforms
+      finish("transform_buffer_target", target)
+    end
+
+    def transform(scope, transform, mode, options = {})
+      @transforms << {
+        "scope" => scope,
+        "transform" => transform,
+        "mode" => mode,
+        "options" => options
+      }
+    end
+
+    def to_plan
+      config = { "compose" => @rows }
+      config["transform"] = @transforms if @transforms.any?
+      config["output"] = @output if @output
+      Plan.new(config)
+    end
+
+    private
+
+    def finish(action, target)
+      row = @current.dup
+      row["action"] = action
+      row["target"] = target if target
+      row["include"] = "all" if action == "remove_buffer_target" && !row.key?("include")
+      @rows << row
+      @current = {}
+    end
+  end
+end

data/lib/markdown_composer/registries/action_entries.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  module ActionRegistryEntries
+    private
+
+    def action_entries
+      {
+        set: [ "Set", "Set the output buffer to this content.", "Set (action) the output buffer from [Source] (source) using [Select] (select), including [Include] (include).", :default, "output", true, :normal ],
+        append: [ "Append", "Append this content to the output buffer.", "Append (action) to the output buffer from [Source] (source) using [Select] (select), including [Include] (include).", :default, "end", true, :normal ],
+        prepend: [ "Prepend", "Prepend this content to the output buffer.", "Prepend (action) to the output buffer from [Source] (source) using [Select] (select), including [Include] (include).", :default, "start", true, :normal ],
+        insert_before: [ "Insert Before", "Insert this content before a target in the output buffer.", "Insert before (action) [Target] (target) from [Source] (source) using [Select] (select), including [Include] (include).", :required, nil, true, :normal ],
+        insert_after: [ "Insert After", "Insert this content after a target in the output buffer.", "Insert after (action) [Target] (target) from [Source] (source) using [Select] (select), including [Include] (include).", :required, nil, true, :normal ],
+        insert_between: [ "Insert Between", "Insert this content between two targets in the output buffer.", "Insert between (action) [Target] (target) from [Source] (source) using [Select] (select), including [Include] (include).", :required, nil, true, :advanced ],
+        replace: [ "Replace", "Replace target content in the output buffer with this content.", "Replace (action) [Target] (target) in the output buffer with content from [Source] (source) using [Select] (select), including [Include] (include).", :required, nil, true, :normal ],
+        copy: [ "Copy", "Copy this content to a target in the output buffer.", "Copy (action) content from [Source] (source) to [Target] (target) using [Select] (select), including [Include] (include).", :required, nil, true, :advanced ],
+        move: [ "Move", "Move selected content within the output buffer.", "Move (action) content within the output buffer using [Select] (select), including [Include] (include), to [Target] (target).", :required, nil, true, :advanced ],
+        modify: [ "Modify", "Transform selected source content, then place the transformed fragment in the output buffer.", "Modify (action) content from [Source] (source) using [Select] (select), including [Include] (include), transform it with [Transform] (transform), [Mode] (mode), using [Options] (options), then place it at [Target] (target).", :default, "end", true, :normal ],
+        remove_buffer_target: [ "Remove Buffer Target", "Remove target content from the output buffer.", "Remove buffer target (action) [Target] (target) from the output buffer.", :required, nil, false, :normal ],
+        transform_buffer_target: [ "Transform Buffer Target", "Transform target content in the output buffer.", "Transform buffer target (action) [Target] (target) in the output buffer with [Transform] (transform), [Mode] (mode), using [Options] (options).", :required, nil, false, :advanced ]
+      }.map do |token, (label, tooltip, row_sentence, target_rule, default_target, uses_selected_content, support)|
+        RegistryEntry.new(token: token.to_s, aliases: [ label.downcase.tr(" ", "_") ], label: label, tooltip: tooltip, meaning: row_sentence, row_sentence: row_sentence, support: { action: support, target_rule: target_rule, default_target: default_target, uses_selected_content: uses_selected_content }, source_formats: [], condition_fields: [])
+      end
+    end
+  end
+end

data/lib/markdown_composer/registries/condition_entries.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  module WhereRegistryEntries
+    private
+
+    def condition_field_entries
+      @condition_field_entries ||= [
+        [ "title", "Title", "Match heading title text.", %w[contains starts_with ends_with equals matches], :text, true ],
+        [ "text", "Text", "Match visible text content.", %w[contains starts_with ends_with equals matches], :text, true ],
+        [ "source_text", "Source Text", "Match retained source representation.", %w[contains starts_with ends_with equals matches], :text, true ],
+        [ "position", "Position", "Match by 1-based position or inclusive range.", %w[equals range], :ordered, false ],
+        [ "language", "Code Language", "Match fenced code language.", %w[equals], :code, false ],
+        [ "diagram_type", "Diagram Type", "Match normalised Mermaid diagram type.", %w[equals], :mermaid, false ],
+        [ "format", "Data Format", "Match structured data format.", %w[equals], :data, false ],
+        [ "location", "Data Location", "Match where structured data came from.", %w[equals], :data, false ],
+        [ "links", "Has Links", "Match units containing links.", %w[exists], :nested, false ],
+        [ "images", "Has Images", "Match units containing images.", %w[exists], :nested, false ],
+        [ "code", "Has Code", "Match units containing code.", %w[exists], :nested, false ],
+        [ "numbers", "Has Numbers", "Match text containing digits.", %w[exists], :text, false ],
+        [ "empty", "Empty", "Match empty or non-empty units.", %w[equals], :node, false ],
+        [ "length", "Text Length", "Match by character length.", %w[min max range], :text, false ],
+        [ "word_count", "Word Count", "Match by word count.", %w[min max range], :text, false ],
+        [ "child", "Has Child", "Match units with nested child sections.", %w[exists], :section, false ]
+      ].map do |token, label, tooltip, predicates, applies_to, field_take|
+        ConditionFieldRegistryEntry.new(token: token, aliases: [], label: label, tooltip: tooltip, meaning: tooltip, predicates: predicates, applies_to: applies_to, source_formats: %i[markdown html], field_take: field_take)
+      end
+    end
+
+    def predicate_entries
+      @predicate_entries ||= [
+        [ "contains", "Contains", "Match when the field includes this text.", :text, :normal ],
+        [ "starts_with", "Starts With", "Match when the field starts with this text.", :text, :normal ],
+        [ "ends_with", "Ends With", "Match when the field ends with this text.", :text, :normal ],
+        [ "equals", "Equals", "Match exact normalised value.", :scalar, :normal ],
+        [ "range", "Range", "Match values inside an inclusive range.", :range, :normal ],
+        [ "exists", "Exists", "Match when this content exists.", :none, :normal ],
+        [ "min", "Minimum", "Match values at or above this minimum.", :number, :normal ],
+        [ "max", "Maximum", "Match values at or below this maximum.", :number, :normal ],
+        [ "matches", "Matches Regex", "Match with a host-approved regular expression.", :regex, :advanced ]
+      ].map do |token, label, tooltip, value_type, support|
+        PredicateRegistryEntry.new(token: token, aliases: [], label: label, tooltip: tooltip, meaning: tooltip, value_type: value_type, support: { predicate: support })
+      end
+    end
+
+    def where_group_entries
+      @where_group_entries ||= [
+        [ "all", "All", "Every child condition must match.", :many ],
+        [ "any", "Any", "At least one child condition must match.", :many ],
+        [ "none", "None", "No child condition may match.", :many ],
+        [ "not", "Not", "Negate one condition or group.", :one ],
+        [ "xor", "Exactly One", "Exactly one child condition must match.", :many ]
+      ].map do |token, label, tooltip, arity|
+        WhereGroupRegistryEntry.new(token: token, aliases: [], label: label, tooltip: tooltip, meaning: tooltip, arity: arity)
+      end
+    end
+  end
+end