coradoc 1.1.8 → 2.0.12

data/lib/coradoc/format_module.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Declared interface contract for format modules.
+  #
+  # Format modules registered via Coradoc.register_format must implement:
+  #
+  # Required:
+  # - parse_to_core(input, options={}) → CoreModel::Base
+  # - serialize(model, **options) → String
+  #
+  # Optional:
+  # - parse(input, options={}) → format-specific model
+  # - handles_model?(model) → Boolean
+  # - to_core(model) → CoreModel::Base
+  # - serialize? → Boolean
+  #
+  module FormatModule
+    MINIMUM_PARSE_METHODS = %i[parse_to_core parse].freeze
+    REQUIRED_METHODS = %i[serialize].freeze
+
+    # Default implementations for optional format module methods.
+    # Format modules are auto-extended with this during registration.
+    module Interface
+      def handles_model?(_model)
+        false
+      end
+
+      def serialize?
+        true
+      end
+    end
+
+    # Validate that a format module implements the minimum interface.
+    # Warns to $stderr if methods are missing. Returns true if valid.
+    def self.validate!(format_module, format_name)
+      has_parse = MINIMUM_PARSE_METHODS.any? { |m| format_module.public_methods.include?(m) }
+      has_serialize = REQUIRED_METHODS.all? { |m| format_module.public_methods.include?(m) }
+
+      return true if has_parse && has_serialize
+
+      missing = []
+      missing << 'parse_to_core or parse' unless has_parse
+      missing << 'serialize' unless has_serialize
+      warn "Coradoc: format :#{format_name} (#{format_module}) missing: #{missing.join(', ')}"
+      false
+    end
+  end
+end

data/lib/coradoc/hooks.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Coradoc
+  module Hooks
+    HOOK_POINTS = {
+      before_parse: 'Called before parsing text content. Receives (content, format:, **options). Should return modified content.',
+      after_parse: 'Called after parsing. Receives (model, format:, **options). Should return modified model.',
+      before_transform: 'Called before transforming model. Receives (model, direction:, **options). Should return modified model.',
+      after_transform: 'Called after transforming model. Receives (model, direction:, **options). Should return modified model.',
+      before_serialize: 'Called before serializing model. Receives (model, format:, **options). Should return modified model.',
+      after_serialize: 'Called after serializing. Receives (output, format:, **options). Should return modified output.',
+      on_error: 'Called when an error occurs. Receives (error, context). Can re-raise or return fallback value.'
+    }.freeze
+
+    class << self
+      attr_accessor :strict_mode
+
+      def register(hook_point, priority: 100, name: nil, &block)
+        validate_hook_point!(hook_point)
+        validate_block!(block, hook_point)
+
+        hook_id = name || generate_hook_id(hook_point)
+        registry[hook_point] ||= []
+        registry[hook_point] << {
+          id: hook_id,
+          priority: priority,
+          sequence: next_sequence,
+          callback: block
+        }
+        registry[hook_point].sort_by! { |h| [h[:priority], h[:sequence]] }
+        hook_id
+      end
+
+      def remove(hook_point, hook_id)
+        validate_hook_point!(hook_point)
+        return false unless registry[hook_point]
+
+        original_size = registry[hook_point].size
+        registry[hook_point].reject! { |h| h[:id] == hook_id }
+        registry[hook_point].size < original_size
+      end
+
+      def clear(hook_point)
+        validate_hook_point!(hook_point)
+        removed = registry[hook_point]&.size || 0
+        registry.delete(hook_point)
+        removed
+      end
+
+      def clear_all
+        total = registry.values.sum(&:size)
+        @registry = {}
+        @sequence_counter = nil
+        total
+      end
+
+      def registered?(hook_point)
+        validate_hook_point!(hook_point)
+        registry[hook_point]&.any? || false
+      end
+
+      def list(hook_point = nil)
+        if hook_point
+          validate_hook_point!(hook_point)
+          registry[hook_point]&.map { |h| h.merge(point: hook_point) } || []
+        else
+          registry.flat_map do |point, hooks|
+            hooks.map { |h| h.merge(point: point) }
+          end
+        end
+      end
+
+      def invoke(hook_point, *args, **kwargs)
+        validate_hook_point!(hook_point)
+        return args.first if args.one? && !registry[hook_point]&.any?
+
+        result = args.first
+        registry[hook_point].each do |hook|
+          result = invoke_hook(hook[:callback], result, args, kwargs)
+        end
+        result
+      end
+
+      def with_hooks(hook_point, *args, **kwargs)
+        validate_hook_point!(hook_point)
+
+        modified_args = invoke(hook_point, *args, **kwargs)
+        result = yield(*modified_args)
+
+        after_point = "after_#{hook_point.to_s.sub('before_', '')}".to_sym
+        result = invoke(after_point, result, **kwargs) if HOOK_POINTS.key?(after_point)
+
+        result
+      rescue StandardError => e
+        invoke_error_hooks(e, hook_point, args, kwargs)
+      end
+
+      def documentation(hook_point = nil)
+        if hook_point
+          validate_hook_point!(hook_point)
+          HOOK_POINTS[hook_point]
+        else
+          HOOK_POINTS.dup
+        end
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+
+      def next_sequence
+        @sequence_counter = (@sequence_counter || 0) + 1
+      end
+
+      def validate_hook_point!(hook_point)
+        return if HOOK_POINTS.key?(hook_point)
+
+        valid_points = HOOK_POINTS.keys.join(', ')
+        raise ArgumentError,
+              "Unknown hook point: #{hook_point}. Valid points: #{valid_points}"
+      end
+
+      def validate_block!(block, hook_point)
+        return if block
+
+        raise ArgumentError,
+              "Block required for hook registration: #{hook_point}"
+      end
+
+      def generate_hook_id(hook_point)
+        "#{hook_point}_#{SecureRandom.hex(8)}"
+      end
+
+      def invoke_hook(callback, result, _args, kwargs)
+        arity = callback.arity
+
+        if kwargs.empty?
+          case arity
+          when 0
+            callback.call
+          else
+            callback.call(result)
+          end
+        else
+          callback.call(result, **kwargs)
+        end
+      rescue StandardError => e
+        raise if @strict_mode
+
+        Coradoc::Logger.warn("Hook failed: #{e.message}")
+        result
+      end
+
+      def invoke_error_hooks(error, hook_point, args, kwargs)
+        context = {
+          hook_point: hook_point,
+          args: args,
+          kwargs: kwargs
+        }
+
+        if registry[:on_error]&.any?
+          registry[:on_error].each do |hook|
+            result = hook[:callback].call(error, context)
+            return result if result
+          end
+        end
+
+        raise error
+      end
+    end
+  end
+end

data/lib/coradoc/input.rb

@@ -1,12 +1,22 @@
-require "coradoc"
+# frozen_string_literal: true
+
+require_relative 'processor_registry'
 
 module Coradoc
+  # Input module for document ingestion
+  #
+  # Provides a unified interface for document input processing.
+  # Format-specific input processors register themselves with this module.
+  #
+  # @example Registering an input processor
+  #   Coradoc::Input.define(MyHtmlProcessor)
+  #
+  # @example Using a registered processor
+  #   processor = Coradoc::Input.for(:html)
+  #   document = processor.convert(html_content)
+  #
   module Input
-    @processors = {}
-    extend Converter::CommonInputOutputMethods
+    extend ProcessorRegistry
+    self.error_label = 'input processor'
   end
 end
-
-require "coradoc/input/adoc"
-require "coradoc/input/docx"
-require "coradoc/input/html"

data/lib/coradoc/logger.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Coradoc
+  class Logger
+    BADGE = 'Coradoc'
+
+    COLORS = {
+      error: "\e[31m", # Red
+      info: "\e[34m", # Blue
+      reset: "\e[m", # Reset
+      success: "\e[32m", # Green
+      warn: "\e[33m", # Yellow
+      bold: "\e[1m",
+      unbold: "\e[22m"
+    }.freeze
+
+    def self.error(message)
+      log(message, :error)
+    end
+
+    def self.info(message)
+      log(message, :info)
+    end
+
+    def self.success(message)
+      log(message, :success)
+    end
+
+    def self.warn(message)
+      log(message, :warn)
+    end
+
+    def self.log(message, type)
+      Warning.warn format_message(message, type)
+    end
+
+    def self.format_message(message, type)
+      colorize(
+        "\n[#{BADGE}] #{COLORS[:bold]}#{type.upcase}#{COLORS[:unbold]}" \
+        ": #{message}\n",
+        type
+      )
+    end
+
+    def self.colorize(message, type)
+      io = type == :warn ? $stderr : $stdout
+      return message unless io.tty?
+
+      "#{COLORS[type]}#{message}#{COLORS[:reset]}"
+    end
+
+    private_class_method :log, :format_message, :colorize
+  end
+end

data/lib/coradoc/output.rb

@@ -1,11 +1,22 @@
-require "coradoc"
+# frozen_string_literal: true
+
+require_relative 'processor_registry'
 
 module Coradoc
+  # Output module for document serialization
+  #
+  # Provides a unified interface for document output processing.
+  # Format-specific output processors register themselves with this module.
+  #
+  # @example Registering an output processor
+  #   Coradoc::Output.define(MyHtmlProcessor)
+  #
+  # @example Using a registered processor
+  #   processor = Coradoc::Output.get(:html_static)
+  #   html = processor.processor_execute(document, {})
+  #
   module Output
-    @processors = {}
-    extend Converter::CommonInputOutputMethods
+    extend ProcessorRegistry
+    self.error_label = 'output processor'
   end
 end
-
-require "coradoc/output/adoc"
-require "coradoc/output/coradoc_tree_debug"

data/lib/coradoc/performance_regression.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'benchmark'
+require 'json'
+
+module Coradoc
+  module PerformanceRegression
+    THRESHOLDS = {
+      markdown_parse_small: 2.0,
+      markdown_parse_medium: 3.0,
+      asciidoc_parse: 5.0,
+      html_serialize: 5.0,
+      md_to_html: 10.0,
+      adoc_to_html: 10.0,
+      core_model_creation: 1.0
+    }.freeze
+
+    BenchmarkResult = Struct.new(:name, :duration, :iterations, :threshold, keyword_init: true) do
+      def to_h
+        { name:, duration:, iterations:, threshold:, passed: passed? }
+      end
+
+      def passed?
+        duration < threshold
+      end
+    end
+
+    ComparisonResult = Struct.new(:name, :duration, :baseline, keyword_init: true) do
+      def regressed?(pct = 0.2)
+        return false if baseline.nil? || baseline.zero?
+
+        (duration - baseline).abs / baseline > pct
+      end
+    end
+
+    class << self
+      def run_all(iterations: 3)
+        benchmarks = build_benchmarks
+        benchmarks.map do |name, threshold, block|
+          times = []
+          iterations.times { times << Benchmark.realtime { block.call } }
+          avg = times.sum / times.size
+          BenchmarkResult.new(name:, duration: avg, iterations:, threshold:)
+        end
+      end
+
+      def run_all_with_summary(iterations: 3)
+        results = run_all(iterations:)
+        failed = results.count { |r| !r.passed? }
+        { results:, failed_count: failed, total: results.size }
+      end
+
+      def print_results(summary)
+        results = summary[:results]
+        results.each do |r|
+          status = r.passed? ? 'PASS' : 'FAIL'
+          puts "  #{status} #{r.name}: #{r.duration.round(4)}s (threshold: #{r.threshold}s)"
+        end
+        puts
+        puts "#{summary[:total] - summary[:failed_count]}/#{summary[:total]} passed"
+      end
+
+      def compare_with_baseline(baseline_path, iterations: 3)
+        return [] unless File.exist?(baseline_path)
+
+        baseline_data = JSON.parse(File.read(baseline_path))
+        baseline_map = baseline_data.each_with_object({}) { |d, m| m[d['name']] = d['duration'] }
+
+        results = run_all(iterations:)
+        results.map do |r|
+          ComparisonResult.new(name: r.name, duration: r.duration, baseline: baseline_map[r.name])
+        end
+      end
+
+      private
+
+      def build_benchmarks
+        sample = {
+          markdown_small: "# Title\n\n#{'Paragraph ' * 10}",
+          markdown_medium: "# Title\n\n#{'Content. ' * 100}\n\n## Section\n\n#{'More. ' * 100}",
+          asciidoc: "= Title\nAuthor\n\n== Section\n\n#{'Paragraph content. ' * 50}",
+          html_doc: Coradoc::CoreModel::DocumentElement.new(
+            title: 'Bench',
+            children: [
+              Coradoc::CoreModel::Block.new(element_type: 'paragraph', content: 'Test')
+            ]
+          )
+        }
+
+        [
+          [:markdown_parse_small, THRESHOLDS[:markdown_parse_small],
+           -> { Coradoc::Markdown.parse(sample[:markdown_small]) }],
+          [:markdown_parse_medium, THRESHOLDS[:markdown_parse_medium],
+           -> { Coradoc::Markdown.parse(sample[:markdown_medium]) }],
+          [:asciidoc_parse, THRESHOLDS[:asciidoc_parse],
+           -> { Coradoc.parse(sample[:asciidoc], format: :asciidoc) }],
+          [:html_serialize, THRESHOLDS[:html_serialize],
+           -> { Coradoc::Html.serialize_static(sample[:html_doc]) }],
+          [:md_to_html, THRESHOLDS[:md_to_html],
+           -> { Coradoc.convert(sample[:markdown_small], from: :markdown, to: :html) }],
+          [:adoc_to_html, THRESHOLDS[:adoc_to_html],
+           -> { Coradoc.convert(sample[:asciidoc], from: :asciidoc, to: :html) }],
+          [:core_model_creation, THRESHOLDS[:core_model_creation],
+           -> { 1000.times { Coradoc::CoreModel::Block.new(element_type: 'paragraph', content: 'x') } }]
+        ]
+      end
+    end
+  end
+end

data/lib/coradoc/processor_registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Module adapter that gives a module Registry-backed processor methods.
+  #
+  # Both Input and Output extend this module to get processor registration,
+  # lookup, and dispatch methods. All state is stored in a Registry instance.
+  #
+  # @api private
+  #
+  # @example
+  #   module Input
+  #     extend ProcessorRegistry
+  #     self.error_label = "input processor"
+  #   end
+  module ProcessorRegistry
+    def error_label=(label)
+      @error_label = label
+    end
+
+    def registry
+      @registry ||= Registry.new(error_label: @error_label)
+    end
+
+    def define(processor, **options)
+      registry.define(processor, **options)
+    end
+
+    def get(id)
+      registry.get(id)
+    end
+    alias [] get
+
+    def registered?(id)
+      registry.registered?(id)
+    end
+
+    def processors
+      registry.items
+    end
+
+    def for_file(filename)
+      registry.for_file(filename)
+    end
+
+    def process(content, options = {})
+      registry.process(content, options)
+    end
+  end
+end