markdown_composer 0.7.0

data/lib/markdown_composer/validator.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  class Validator
+    attr_reader :plan, :sources, :options, :diagnostics
+
+    def initialize(plan, sources: [], options: {}, diagnostics: Diagnostics.new)
+      @plan = plan
+      @sources = Array(sources)
+      @options = options
+      @diagnostics = diagnostics
+    end
+
+    def call
+      validate_output
+      validate_steps
+      validate_transforms
+      diagnostics.concat(plan.diagnostics)
+      diagnostics
+    end
+
+    private
+
+    def validate_output
+      diagnostics.error("output.invalid", "Output must be markdown or html", path: "output") unless %w[markdown html].include?(plan.output)
+    end
+
+    def validate_steps
+      buffer_available = options.fetch(:initial_buffer, nil).to_s.strip != ""
+      previous_source = nil
+      plan.steps.each_with_index do |step, index|
+        path = "compose[#{index}]"
+        source = effective_source_ref(step["source"], previous_source)
+        validate_source(source, path: "#{path}.source", buffer_available: buffer_available, original_type: step.dig("source", "type"))
+        validate_selector(step["select"], :select, path: "#{path}.select")
+        Array(step["include"]).each_with_index { |item, item_index| validate_include(item, path: "#{path}.include[#{item_index}]", inside_data_block: data_block_selector?(step["select"])) }
+        validate_action(step.merge("source" => source, "_original_source_type" => step.dig("source", "type")), path: path)
+        validate_target(step["target"], path: "#{path}.target") if step["target"]
+        validate_row_transforms(step, path: path) if step["transforms"]
+        buffer_available ||= action_produces_buffer?(step)
+        previous_source = source
+      end
+    end
+
+    def effective_source_ref(source, previous_source)
+      return source unless source&.fetch("type", nil) == "previous"
+
+      previous_source || { "type" => "current" }
+    end
+
+    def validate_source(source, path:, buffer_available: true, original_type: nil)
+      type = source&.fetch("type", nil)
+      diagnostics.error("source.unknown", "Unknown source type #{type.inspect}", path: path) unless Registries.default.sources[type]
+      case type
+      when "explicit"
+        diagnostics.error("source.identifier_missing", "explicit source requires key, id, or slug", path: path) unless source["key"] || source["id"] || source["slug"]
+      when "inherited"
+        diagnostics.error("source.inherited_key_missing", "inherited source requires from, key, id, or slug", path: path) unless source["from"] || source["key"] || source["id"] || source["slug"]
+      when "inline"
+        diagnostics.error("source.inline_empty", "inline source requires markdown or html content", path: path) if source["markdown"].to_s.empty? && source["html"].to_s.empty?
+      when "current"
+        current_sources = sources.select { |candidate| candidate.type == "current" }
+        diagnostics.error("source.current_ambiguous", "current source is ambiguous; provide a key", path: path) if current_sources.length > 1 && !source["key"]
+        diagnostics.error("source.previous_current_missing", "previous source has no previous row and no current source", path: path) if original_type == "previous" && current_sources.empty? && !source["key"]
+      when "buffer"
+        diagnostics.error("source.buffer_unavailable", "buffer source requires previous output", path: path) unless buffer_available
+      end
+    end
+
+    def validate_selector(selector, consumer, path:)
+      Array(selector["types"] || selector["type"]).each do |type|
+        validate_unit_token(type, consumer, path: path)
+      end
+      Take.validate(selector["take"] || {}).each do |message|
+        diagnostics.error("take.invalid", contextual_message("#{path}.take", take_message(message)), path: "#{path}.take")
+      end
+      Where.validate(selector["where"], diagnostics: diagnostics, path: "#{path}.where", options: options) if selector["where"]
+      Array(selector["include"]).each_with_index { |item, index| validate_include(item, path: "#{path}.include[#{index}]", inside_data_block: data_block_selector?(selector)) }
+    end
+
+    def validate_include(item, path:, inside_data_block: false)
+      if item["exclude"]
+        validate_include(item["exclude"], path: "#{path}.exclude", inside_data_block: inside_data_block)
+        return
+      end
+      if item["type"] == "data_path"
+        diagnostics.error("data_path.scope_invalid", "data_path is only valid inside data_block include scope", path: path) unless inside_data_block
+        diagnostics.error("data_path.path_missing", "data_path requires a path", path: "#{path}.path") if item["path"].to_s.strip.empty?
+        return
+      end
+      validate_selector(item, :include, path: path)
+    end
+
+    def validate_target(target, path:)
+      unless target
+        diagnostics.error("target.missing", "Target is missing", path: path)
+        return
+      end
+      return if %w[output start end in_place].include?(target["position"].to_s)
+
+      if target["placement"] == "between"
+        diagnostics.error("target.between_missing", "Between target requires start and end anchors", path: path) unless target["start"] && target["end"]
+        validate_target(target["start"], path: "#{path}.start")
+        validate_target(target["end"], path: "#{path}.end")
+      else
+        validate_selector(target, :target, path: path)
+      end
+    end
+
+    def validate_action(step, path:)
+      action = step["action"]
+      entry = Registries.default.actions[action]
+      unless entry
+        diagnostics.error("action.unknown", "Unknown action #{action.inspect}", path: "#{path}.action")
+        return
+      end
+
+      target_rule = entry.support[:target_rule]
+      diagnostics.error("action.target_required", "#{action} requires a target", path: "#{path}.target") if target_rule == :required && !step["target"]
+      if %w[modify transform_buffer_target].include?(action) && Array(step["transforms"]).empty?
+        diagnostics.error("action.transform_definition_missing", "#{action} requires transforms", path: "#{path}.transforms")
+      end
+      diagnostics.error("action.move_source_invalid", "move should use source type buffer", path: "#{path}.source") if action == "move" && step.dig("source", "type") != "buffer"
+      return unless step["target"]
+
+      placement = step.dig("target", "placement")
+      diagnostics.error("target.placement_conflict", "insert_before target placement must be before", path: "#{path}.target") if action == "insert_before" && placement && placement != "before"
+      diagnostics.error("target.placement_conflict", "insert_after target placement must be after", path: "#{path}.target") if action == "insert_after" && placement && placement != "after"
+      diagnostics.error("target.between_required", "insert_between requires a Between target", path: "#{path}.target") if action == "insert_between" && placement != "between"
+      diagnostics.error("target.selector_required", "#{action} requires selector target, not start/end", path: "#{path}.target") if %w[remove_buffer_target transform_buffer_target].include?(action) && step.dig("target", "position")
+      validate_in_place_target(step, path: path) if step.dig("target", "position") == "in_place"
+    end
+
+    def validate_in_place_target(step, path:)
+      action = step["action"]
+      diagnostics.error(
+        "target.in_place_action_invalid",
+        "target in_place is only valid with action modify",
+        path: "#{path}.target"
+      ) unless action == "modify"
+
+      return if step["_original_source_type"] == "buffer"
+
+      diagnostics.error(
+        "target.in_place_source_invalid",
+        "target in_place requires source type buffer",
+        path: "#{path}.source"
+      )
+    end
+
+    def validate_row_transforms(step, path:)
+      Array(step["transforms"]).each_with_index do |transform, index|
+        if step["action"] == "transform_buffer_target" && transform["_scope_missing"]
+          next unless step["target"]
+
+          transform = transform.merge("scope" => step["target"])
+        end
+        validate_transform(transform, path: "#{path}.transforms[#{index}]")
+      end
+    end
+
+    def validate_transforms
+      plan.transforms.each_with_index do |transform, index|
+        validate_transform(transform, path: "transform[#{index}]")
+      end
+    end
+
+    def validate_transform(transform, path:)
+      validate_selector(transform["scope"], :scope, path: "#{path}.scope")
+      entry = Registries.default.transforms[transform["transform"]]
+      unless entry
+        diagnostics.error("transform.unknown", "Unknown transform #{transform["transform"].inspect}", path: path)
+        return
+      end
+
+      support = entry.support[:transform]
+      diagnostics.error("transform.policy_disabled", "#{transform["transform"]} requires adapter policy", path: path) if support == :adapter_policy && !options.fetch(:adapter_transforms, false)
+      modes = entry.support[:modes]
+      diagnostics.error("transform.mode_invalid", "Invalid mode #{transform["mode"].inspect} for #{entry.token}", path: "#{path}.mode") if modes.any? && !modes.include?(transform["mode"].to_s)
+      validate_transform_options(transform, path: path)
+    end
+
+    def validate_transform_options(transform, path:)
+      options_hash = transform["options"] || {}
+      return if plan.diagnostics.errors.any? { |diagnostic| diagnostic.code == "transform.options_syntax" && diagnostic.path == "#{path}.options" }
+
+      allowed = allowed_transform_options(transform)
+      options_hash.each_key do |key|
+        diagnostics.error("transform.option_unknown", "Unknown option #{key} for #{transform["transform"]}", path: "#{path}.options.#{key}") unless allowed.include?(key)
+      end
+
+      required = TransformOptions.required(transform["transform"], transform["mode"])
+
+      required.each do |key|
+        diagnostics.error("transform.option_missing", "Missing required option #{key}", path: "#{path}.options.#{key}") unless options_hash.key?(key)
+      end
+      if options_hash["content"].to_s.match?(/\{\{|\}\}/)
+        diagnostics.error("transform.option_invalid", "content uses template braces; use Composer scoped fields such as field[text]", path: "#{path}.options.content")
+      end
+      validate_content_fields(options_hash["content"], path: "#{path}.options.content") if options_hash.key?("content")
+      if options_hash.key?("parse_as") && !%w[markdown text html].include?(options_hash["parse_as"].to_s)
+        diagnostics.error("transform.option_invalid", "parse_as must be markdown, text, or html", path: "#{path}.options.parse_as")
+      end
+      if options_hash.key?("case_sensitive") && !boolean?(options_hash["case_sensitive"])
+        diagnostics.error("transform.option_invalid", "case_sensitive must be true or false", path: "#{path}.options.case_sensitive")
+      end
+      if options_hash.key?("skip_if_present") && !boolean?(options_hash["skip_if_present"])
+        diagnostics.error("transform.option_invalid", "skip_if_present must be true or false", path: "#{path}.options.skip_if_present")
+      end
+
+      keys_requiring_unit = %w[as unit]
+      keys_requiring_unit << "to" if transform["transform"] == "heading_levels"
+      keys_requiring_unit.each do |key|
+        next unless options_hash[key].is_a?(String)
+        next if Registries.default.unit_tokens[options_hash[key]]
+
+        diagnostics.error("transform.option_invalid", "#{key} is not a valid unit token", path: "#{path}.options.#{key}")
+      end
+      %w[by limit start].each do |key|
+        next unless options_hash.key?(key)
+
+        diagnostics.error("transform.option_invalid", "#{key} must be a positive integer", path: "#{path}.options.#{key}") if options_hash[key].to_i <= 0
+      end
+      diagnostics.error("transform.output_invalid", "sanitise requires HTML output", path: path) if transform["transform"] == "sanitise" && plan.output != "html"
+      validate_target(options_hash["target"], path: "#{path}.options.target") if options_hash["target"].is_a?(Hash)
+    end
+
+    def allowed_transform_options(transform)
+      TransformOptions.allowed(transform["transform"], transform["mode"], adapter_option_keys: options[:adapter_option_keys])
+    end
+
+    def boolean?(value)
+      value == true || value == false
+    end
+
+    def validate_content_fields(content, path:)
+      content.to_s.scan(/field\[([a-z_][a-z0-9_]*(?::[a-z0-9_]+)?(?:\.[a-z_][a-z0-9_]*(?::[a-z0-9_]+)?)*(?:\[[^\]]+\])?)\]/).flatten.each do |reference|
+        next if valid_content_field_reference?(reference)
+
+        diagnostics.error("transform.option_invalid", "Unknown scoped content field field[#{reference}]", path: path)
+      end
+    end
+
+    def valid_content_field_reference?(reference)
+      reference = reference.to_s.sub(/\[[^\]]+\]\z/, "")
+      parts = reference.to_s.split(".")
+      return valid_current_field?(parts.first) if parts.length == 1
+
+      case parts.first
+      when "current"
+        parts.length == 2 && valid_current_field?(parts.last)
+      when "section"
+        valid_section_reference?(parts)
+      when "parent_section"
+        parts.length == 2 && valid_section_field?(parts.last)
+      else
+        false
+      end
+    end
+
+    def valid_current_field?(field)
+      %w[
+        text source_text type index start_line end_line title level number
+        href src alt language diagram_type format location item_count ordered
+        item_index row_count column_count row_index column_index section
+        path key value
+      ].include?(field.to_s)
+    end
+
+    def valid_section_field?(field)
+      %w[title level text source_text type index start_line end_line number].include?(field.to_s)
+    end
+
+    def valid_section_reference?(parts)
+      return parts.length == 2 && valid_section_field?(parts.last) if parts[1] && valid_section_field?(parts[1])
+      return true if parts.length == 3 && parts[1] == "parent" && valid_section_field?(parts.last)
+      return true if parts.length == 4 && parts[1] == "parent" && parts[2] == "parent" && valid_section_field?(parts.last)
+      return true if parts.length == 3 && valid_ancestor_reference?(parts[1]) && valid_section_field?(parts.last)
+
+      false
+    end
+
+    def valid_ancestor_reference?(part)
+      return false unless part.to_s.start_with?("ancestor:")
+
+      heading = part.split(":", 2).last
+      token = Registries.default.unit_tokens.normalise(heading) || heading.to_s
+      token.match?(/\Aheading_[1-6]\z/)
+    end
+
+    def validate_unit_token(type, consumer, path:)
+      entry = Registries.default.unit_tokens[type]
+      unless entry
+        diagnostics.error("token.unknown", contextual_message(path, unknown_token_message(type)), path: path)
+        return
+      end
+
+      diagnostics.error("token.unsupported", contextual_message(path, "#{type} is not supported for #{consumer}"), path: path) unless entry.supports?(consumer, options)
+    end
+
+    def data_block_selector?(selector)
+      Array(selector["types"] || selector["type"]).map(&:to_s).include?("data_block")
+    end
+
+    def action_produces_buffer?(step)
+      step["action"] != "remove_buffer_target"
+    end
+
+    def contextual_message(path, message)
+      "#{human_path(path)}: #{message}"
+    end
+
+    def human_path(path)
+      row_index = path[/compose\[(\d+)\]/, 1]
+      return path unless row_index
+
+      field = path.sub(/\Acompose\[\d+\]\.?/, "")
+      field = "row" if field.empty?
+      "Row #{row_index.to_i + 1} #{field}"
+    end
+
+    def unknown_token_message(type)
+      value = type.to_s
+      if value.match?(/\b(wher|whre|wheree|were)\b/i)
+        return "Unknown unit token #{value.inspect}. Possible error: the `where` keyword appears misspelled. Use `<unit>[take] where <condition>`."
+      end
+
+      suggestion = closest_unit_token(value)
+      if suggestion
+        "Unknown unit token #{value.inspect}. Did you mean #{suggestion.inspect}?"
+      else
+        "Unknown unit token #{value.inspect}. Check the token spelling against the unit token registry."
+      end
+    end
+
+    def take_message(message)
+      if message =~ /\AUnknown take operator "([^"]+)"\z/
+        operator = Regexp.last_match(1)
+        suggestion = closest_take_operator(operator)
+        return suggestion ? "#{message}. Did you mean #{suggestion.inspect}?" : "#{message}. Check the take modifier spelling."
+      end
+
+      message
+    end
+
+    def closest_unit_token(value)
+      candidates = Registries.default.unit_tokens.tokens
+      candidate = candidates.min_by { |item| edit_distance(value, item) }
+      candidate if candidate && edit_distance(value, candidate) <= 3
+    end
+
+    def closest_take_operator(value)
+      candidates = Registries.default.take.keys.map(&:to_s)
+      candidate = candidates.min_by { |item| edit_distance(value, item) }
+      candidate if candidate && edit_distance(value, candidate) <= 3
+    end
+
+    def edit_distance(left, right)
+      left = left.to_s
+      right = right.to_s
+      costs = (0..right.length).to_a
+      left.each_char.with_index(1) do |left_char, left_index|
+        previous = costs[0]
+        costs[0] = left_index
+        right.each_char.with_index(1) do |right_char, right_index|
+          current = costs[right_index]
+          costs[right_index] = if left_char == right_char
+            previous
+          else
+            [ costs[right_index] + 1, costs[right_index - 1] + 1, previous + 1 ].min
+          end
+          previous = current
+        end
+      end
+      costs[right.length]
+    end
+  end
+end

data/lib/markdown_composer/value_object.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  def self.value_object(*members, &block)
+    Struct.new(*members, keyword_init: true) do
+      def with(attributes)
+        values = {}
+        each_pair { |name, value| values[name] = value }
+        self.class.new(**values.merge(attributes))
+      end
+
+      class_eval(&block) if block
+    end
+  end
+end

data/lib/markdown_composer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  VERSION = "0.7.0"
+end