coradoc 1.1.8 → 2.0.15

data/lib/coradoc/coradoc.rb

@@ -0,0 +1,467 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+# Coradoc - A hub-and-spoke document transformation library
+#
+# Coradoc provides a unified document model (CoreModel) and transformation
+# infrastructure for converting between document formats such as AsciiDoc,
+# HTML, and Markdown.
+#
+# ## Architecture
+#
+# Coradoc uses a hub-and-spoke architecture where CoreModel acts as the
+# canonical document representation. Each format (AsciiDoc, HTML, Markdown)
+# has its own model and transformers to/from CoreModel.
+#
+# ```
+# Source Format → Source Model → CoreModel → Target Model → Target Format
+# ```
+#
+# ## Quick Start
+#
+# @example Parsing documents
+#   require 'coradoc'
+#
+#   # Parse AsciiDoc to CoreModel
+#   doc = Coradoc.parse("= Title\n\nContent", format: :asciidoc)
+#
+# @example Converting between formats
+#   # Convert AsciiDoc to HTML
+#   html = Coradoc.convert(adoc_text, from: :asciidoc, to: :html)
+#
+#   # Convert Markdown to AsciiDoc
+#   adoc = Coradoc.convert(md_text, from: :markdown, to: :asciidoc)
+#
+# @example Using the hooks system
+#   Coradoc::Hooks.register(:before_parse) do |content, format:|
+#     puts "Parsing #{format} document..."
+#     content
+#   end
+#
+# @see Coradoc::CoreModel The canonical document model
+# @see Coradoc::Hooks Plugin lifecycle hooks system
+# @see Coradoc::FormatModule Interface contract for format modules
+#
+module Coradoc
+  # Base error class - defined in errors.rb
+  # @see Coradoc::Error Base error class
+  # @see Coradoc::ParseError Parsing errors with source context
+  # @see Coradoc::ValidationError Document validation errors
+  # @see Coradoc::TransformationError Model transformation errors
+  # @see Coradoc::UnsupportedFormatError Unsupported format errors
+
+  class << self
+    # Get the format registry
+    #
+    # @return [Registry] the format registry
+    def registry
+      @registry ||= Registry.new
+    end
+
+    # Register a format gem
+    #
+    # @param format_name [Symbol] the format name (e.g., :asciidoc, :html, :markdown)
+    # @param format_module [Module] the format module
+    # @param options [Hash] optional configuration (e.g., extensions: [])
+    # @return [void]
+    def register_format(format_name, format_module, **options)
+      format_module.extend(FormatModule::Interface) unless format_module.is_a?(FormatModule::Interface)
+      registry.register(format_name, format_module, options)
+      FormatModule.validate!(format_module, format_name)
+    end
+
+    # Get a registered format
+    #
+    # @param format_name [Symbol] the format name
+    # @return [Module, nil] the format module or nil if not found
+    def get_format(format_name)
+      registry.get(format_name)
+    end
+
+    # List all registered formats
+    #
+    # @return [Array<Symbol>] list of registered format names
+    def registered_formats
+      registry.list
+    end
+
+    # Parse text to a document model
+    #
+    # This is the main entry point for parsing documents. It automatically
+    # selects the appropriate parser based on the format.
+    #
+    # @param text [String] the document text to parse
+    # @param format [Symbol] the source format (:asciidoc, :html, :markdown)
+    # @return [Coradoc::CoreModel::Base, Object] the parsed document model
+    # @raise [UnsupportedFormatError] if the format is not registered
+    #
+    # @example Parse AsciiDoc
+    #   doc = Coradoc.parse("= Title\n\nContent", format: :asciidoc)
+    #   doc = Coradoc.parse(File.read("doc.adoc"), format: :asciidoc)
+    #
+    # @example Parse and get CoreModel
+    #   core = Coradoc.parse(text, format: :asciidoc)  # Returns CoreModel
+    def parse(text, format:)
+      format_module = get_format(format)
+      unless format_module
+        raise UnsupportedFormatError,
+              "Format '#{format}' is not registered. " \
+              "Available formats: #{registered_formats.join(', ')}"
+      end
+
+      text = Hooks.invoke(:before_parse, text, format: format)
+      result = format_module.parse_to_core(text)
+      Hooks.invoke(:after_parse, result, format: format)
+    end
+
+    # Convert document text from one format to another
+    #
+    # This is the main entry point for format conversion. It handles the
+    # complete pipeline: parse -> transform to CoreModel -> transform to target -> serialize
+    #
+    # @param text [String] the source document text
+    # @param from [Symbol] the source format (:asciidoc, :html, :markdown)
+    # @param to [Symbol] the target format (:asciidoc, :html, :markdown)
+    # @param options [Hash] additional options for the conversion
+    # @return [String] the converted document text
+    # @raise [UnsupportedFormatError] if a format is not registered
+    #
+    # @example Convert AsciiDoc to HTML
+    #   html = Coradoc.convert(adoc_text, from: :asciidoc, to: :html)
+    #
+    # @example Convert HTML to AsciiDoc
+    #   adoc = Coradoc.convert(html_text, from: :html, to: :asciidoc)
+    def convert(text, from:, to:, **)
+      # Parse to CoreModel
+      core = parse(text, format: from)
+
+      # Convert to target format
+      serialize(core, to: to, **)
+    end
+
+    # Transform a model to CoreModel
+    #
+    # @param model [Object] a format-specific model
+    # @return [Coradoc::CoreModel::Base] the CoreModel representation
+    def to_core(model)
+      return model if model.is_a?(CoreModel::Base)
+
+      registry.each_value do |format_module|
+        next unless format_module.handles_model?(model)
+
+        return format_module.to_core(model)
+      end
+
+      raise TransformationError, "No transformer found for #{model.class}"
+    end
+
+    # Serialize a CoreModel to a specific format
+    #
+    # @param model [Coradoc::CoreModel::Base] the CoreModel to serialize
+    # @param to [Symbol] the target format
+    # @param options [Hash] additional options
+    # @return [String] the serialized document
+    def serialize(model, to:, **)
+      format_module = get_format(to)
+      raise UnsupportedFormatError, "Format '#{to}' is not registered" unless format_module
+
+      model = Hooks.invoke(:before_serialize, model, format: to)
+      result = format_module.serialize(model, **)
+      Hooks.invoke(:after_serialize, result, format: to)
+    end
+
+    # Create a DocumentManipulator for chainable operations
+    #
+    # @param document [Coradoc::CoreModel::Base] the document to manipulate
+    # @return [DocumentManipulator] a new manipulator instance
+    #
+    # @example Chainable document manipulation
+    #   html = Coradoc.manipulate(doc)
+    #     .transform_text(&:upcase)
+    #     .add_toc
+    #     .to_html
+    def manipulate(document)
+      DocumentManipulator.new(document)
+    end
+
+    # Detect format from a file extension
+    #
+    # @param filename [String] Filename or extension to detect
+    # @return [Symbol, nil] the detected format symbol
+    #
+    # @example
+    #   Coradoc.detect_format("document.adoc")  # => :asciidoc
+    #   Coradoc.detect_format("file.md")        # => :markdown
+    def detect_format(filename)
+      ext = File.extname(filename).downcase
+      registry.each_key do |name|
+        opts = registry.options_for(name)
+        return name if opts[:extensions]&.include?(ext)
+      end
+      nil
+    end
+
+    # Parse a document from a file path
+    #
+    # Handles both text formats (reads file content) and binary formats
+    # (passes file path directly to the format module).
+    #
+    # @param path [String] path to the document file
+    # @param format [Symbol, nil] source format (auto-detected if nil)
+    # @return [Coradoc::CoreModel::Base] the parsed CoreModel document
+    # @raise [UnsupportedFormatError] if format is not detected or registered
+    #
+    # @example
+    #   doc = Coradoc.parse_file("document.adoc")
+    #   doc = Coradoc.parse_file("report.docx", format: :docx)
+    def parse_file(path, format: nil)
+      raise FileNotFoundError, path unless File.exist?(path)
+
+      source_format = format || detect_format(path)
+      raise UnsupportedFormatError, "Could not detect format for: #{path}" unless source_format
+
+      format_module = get_format(source_format)
+      raise UnsupportedFormatError, "Format '#{source_format}' is not registered" unless format_module
+
+      if binary_format?(source_format)
+        format_module.parse_to_core(path)
+      else
+        content = File.read(path)
+        content = Hooks.invoke(:before_parse, content, format: source_format)
+        result = format_module.parse_file_to_core(path, content)
+        Hooks.invoke(:after_parse, result, format: source_format)
+      end
+    end
+
+    # Convert a file from one format to another
+    #
+    # @param path [String] path to the source document file
+    # @param from [Symbol, nil] source format (auto-detected if nil)
+    # @param to [Symbol] target format
+    # @param options [Hash] additional options
+    # @return [String] the converted document text
+    #
+    # @example
+    #   html = Coradoc.convert_file("document.adoc", to: :html)
+    #   adoc = Coradoc.convert_file("report.docx", to: :asciidoc)
+    def convert_file(path, to:, from: nil, **)
+      source_format = from || detect_format(path)
+      raise UnsupportedFormatError, "Could not detect format for: #{path}" unless source_format
+
+      core = parse_file(path, format: source_format)
+      serialize(core, to: to, **)
+    end
+
+    # Check if a format requires binary (file path) input
+    #
+    # @param format [Symbol] the format to check
+    # @return [Boolean] true if the format is binary
+    def binary_format?(format)
+      opts = registry.options_for(format)
+      opts&.fetch(:binary, false) == true
+    end
+
+    # Normalize a format name string to a symbol
+    #
+    # Handles common aliases like "adoc" → :asciidoc, "md" → :markdown.
+    #
+    # @param name [String, Symbol, nil] the format name to normalize
+    # @return [Symbol, nil] the normalized format symbol, or nil
+    def normalize_format(name)
+      return nil unless name
+
+      key = name.to_s.downcase
+      registry.each_key do |fmt_name|
+        opts = registry.options_for(fmt_name)
+        return fmt_name if opts[:aliases]&.include?(key)
+      end
+      key.to_sym
+    end
+
+    # Check if a format supports serialization (writing output)
+    #
+    # @param format [Symbol] the format to check
+    # @return [Boolean] true if the format can serialize
+    def serialize_format?(format)
+      mod = get_format(format)
+      return false unless mod
+
+      mod.serialize?
+    end
+
+    # Check if a format supports parsing (reading input)
+    #
+    # @param format [Symbol] the format to check
+    # @return [Boolean] true if the format can parse
+    def parse_format?(format)
+      mod = get_format(format)
+      return false unless mod
+
+      mod.public_methods.include?(:parse_to_core) || mod.public_methods.include?(:parse)
+    end
+
+    # Get capability summary for all registered formats
+    #
+    # Returns a hash mapping each format name to its capabilities
+    # (parse: bool, serialize: bool). Useful for CLI display and introspection.
+    #
+    # @return [Hash<Symbol, Hash<Symbol, Boolean>>]
+    def format_capabilities
+      registered_formats.each_with_object({}) do |name, caps|
+        caps[name] = {
+          parse: parse_format?(name),
+          serialize: serialize_format?(name)
+        }
+      end
+    end
+
+    # Resolve the output format from a filename, with a default
+    #
+    # @param output_file [String, nil] output filename to detect from
+    # @param default [Symbol] default format when detection fails (default: :html)
+    # @return [Symbol] the resolved format
+    def resolve_output_format(output_file, default: :html)
+      return default unless output_file
+
+      detect_format(output_file) || default
+    end
+
+    # Get file metadata for display
+    #
+    # @param path [String] path to the file
+    # @return [Hash] metadata including :size, :format, and :lines (for text formats)
+    def file_info(path)
+      fmt = detect_format(path)
+      info = { size: File.size(path), format: fmt }
+      info[:lines] = File.foreach(path).count unless binary_format?(fmt)
+      info
+    end
+
+    # Validate a document file
+    #
+    # Parses the file and validates against auto-generated schema.
+    # Returns a Coradoc::Validation::Result.
+    #
+    # @param path [String] path to the document file
+    # @param format [Symbol, nil] source format (auto-detected if nil)
+    # @return [Coradoc::Validation::Result] validation result
+    # @raise [UnsupportedFormatError] if format is not detected or registered
+    def validate_file(path, format: nil)
+      doc = parse_file(path, format: format)
+
+      schema = Validation::SchemaGenerator.generate(doc.class)
+      return schema.validate(doc) if schema
+
+      Validation::Result.new
+    end
+
+    # Gather statistics about a parsed document
+    #
+    # @param doc [CoreModel::Base] parsed document
+    # @return [Hash] statistics including element counts, title, etc.
+    def document_stats(doc)
+      stats = {}
+
+      stats[:title] = doc.title if doc.title
+
+      if doc.is_a?(CoreModel::StructuralElement)
+        stats[:child_count] = count_elements(doc)
+        stats[:element_counts] = count_element_types(doc)
+      end
+
+      stats
+    end
+
+    # Describe an element for display
+    #
+    # @param elem [Object] element to describe
+    # @return [String] human-readable description
+    def describe_element(elem)
+      return elem.to_s unless elem.is_a?(CoreModel::Base)
+
+      type = elem.class.name.split('::').last
+      if elem.title
+        "#{type}: #{elem.title}"
+      elsif elem.is_a?(CoreModel::Block) && elem.content
+        preview = elem.content.to_s[0..50]
+        preview += '...' if elem.content.to_s.length > 50
+        "#{type}: #{preview}"
+      else
+        type
+      end
+    end
+
+    # Strip unicode whitespace from a string
+    #
+    # @param string [String] the string to strip
+    # @param only [Symbol, nil] what to strip: :begin, :end, or nil for both
+    # @return [String] the stripped string
+    def strip_unicode(string, only: nil)
+      return string if string.nil?
+
+      case only
+      when :begin
+        string.sub(/^\p{Zs}+/, '')
+      when :end
+        string.sub(/\p{Zs}+$/, '')
+      else
+        string.sub(/^\p{Zs}+/, '').sub(/\p{Zs}+$/, '')
+      end
+    end
+
+    private
+
+    def count_elements(doc)
+      return 0 unless doc.is_a?(CoreModel::StructuralElement)
+
+      doc.children.sum do |child|
+        1 + (child.is_a?(CoreModel::StructuralElement) ? count_elements(child) : 0)
+      end
+    end
+
+    def count_element_types(doc)
+      counts = Hash.new(0)
+      visitor = Class.new(Visitor::Base) do
+        define_method(:visit) do |element|
+          if element.is_a?(CoreModel::Base)
+            has_element_type = element.is_a?(CoreModel::StructuralElement) || element.is_a?(CoreModel::Block)
+            type_key = if has_element_type && element.element_type
+                         element.element_type
+                       else
+                         element.class.name.split('::').last
+                                .gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, '')
+                       end
+            counts[type_key] += 1
+          end
+          super(element)
+        end
+      end.new
+      visitor.visit(doc)
+      counts.reject! { |_, v| v.zero? }
+      counts
+    end
+  end
+
+  autoload :Error, "#{__dir__}/errors"
+  autoload :Version, "#{__dir__}/version"
+  autoload :Logger, "#{__dir__}/logger"
+  autoload :Hooks, "#{__dir__}/hooks"
+  autoload :Query, "#{__dir__}/query"
+  autoload :Validation, "#{__dir__}/validation"
+  autoload :Configurable, "#{__dir__}/configurable"
+  autoload :FormatModule, "#{__dir__}/format_module"
+  autoload :CoreModel, "#{__dir__}/core_model"
+  autoload :Registry, "#{__dir__}/registry"
+  autoload :Transform, "#{__dir__}/transform"
+  autoload :Input, "#{__dir__}/input"
+  autoload :Output, "#{__dir__}/output"
+  autoload :DocumentManipulator, "#{__dir__}/document_manipulator"
+  autoload :Visitor, "#{__dir__}/visitor"
+  autoload :PerformanceRegression, "#{__dir__}/performance_regression"
+end
+
+# Format gems self-register via Coradoc.register_format when they are required.
+# No hardcoded registration needed here — each gem's entry file handles its own
+# registration (e.g., coradoc-adoc/lib/coradoc/asciidoc.rb calls
+# Coradoc.register_format(:asciidoc, Coradoc::AsciiDoc)).

data/lib/coradoc/core_model/annotation_block.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Specialized block for annotations and admonitions
+    #
+    # Represents annotation blocks that have special semantic meaning:
+    # - NOTE
+    # - WARNING
+    # - CAUTION
+    # - IMPORTANT
+    # - TIP
+    # - Reviewer notes
+    # - Sidebar blocks (when used for annotations)
+    #
+    # This class extends Block to add annotation-specific attributes that
+    # distinguish these blocks semantically from generic delimited blocks.
+    #
+    # @example Creating a NOTE annotation
+    #   note = CoreModel::AnnotationBlock.new(
+    #     annotation_type: "note",
+    #     content: "This is important information."
+    #   )
+    #
+    # @example Creating a reviewer note
+    #   reviewer = CoreModel::AnnotationBlock.new(
+    #     annotation_type: "reviewer",
+    #     annotation_label: "john.doe",
+    #     content: "Please review this section."
+    #   )
+    class AnnotationBlock < Block
+      # @!attribute annotation_type
+      #   @return [String, nil] the type of annotation
+      #     (e.g., 'note', 'warning', 'reviewer', 'sidebar')
+      attribute :annotation_type, :string
+
+      # @!attribute annotation_label
+      #   @return [String, nil] optional custom label or identifier
+      #     (e.g., reviewer ID, custom note label)
+      attribute :annotation_label, :string
+
+      private
+
+      # Attributes to compare for semantic equivalence
+      #
+      # Annotation blocks are semantically different from generic blocks
+      # because they carry additional meaning through annotation_type and
+      # annotation_label. Two blocks with different annotation types are
+      # not semantically equivalent even if their content is identical.
+      #
+      # @return [Array<Symbol>] list of comparable attributes
+      def comparable_attributes
+        super + %i[annotation_type annotation_label]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/base.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Coradoc
+  module CoreModel
+    # Base class for all core models
+    #
+    # Provides common functionality for schema-agnostic document models.
+    # This class establishes the foundational structure for all CoreModel
+    # classes, including semantic equivalence comparison and common
+    # attributes.
+    #
+    # @example Creating a base model
+    #   model = CoreModel::Base.new(
+    #     id: "example-1",
+    #     title: "Example Title",
+    #     element_attributes: [
+    #       CoreModel::ElementAttribute.new(name: "role", value: "note")
+    #     ]
+    #   )
+    #
+    # @example Semantic comparison
+    #   model1 = CoreModel::Base.new(id: "test", title: "Test")
+    #   model2 = CoreModel::Base.new(id: "test", title: "Test")
+    #   model1.semantically_equivalent?(model2) # => true
+    class Base < Lutaml::Model::Serializable
+      # @!attribute id
+      #   @return [String, nil] unique identifier for the element
+      attribute :id, :string
+
+      # @!attribute title
+      #   @return [String, nil] title of the element
+      attribute :title, :string
+
+      # @!attribute element_attributes
+      #   @return [Array<ElementAttribute>] collection of element attributes
+      attribute :element_attributes, ElementAttribute, collection: true
+
+      # @!attribute metadata_entries
+      #   @return [Array<MetadataEntry>] additional metadata entries
+      attribute :metadata_entries, MetadataEntry, collection: true
+
+      # Get all metadata as a hash, or a specific metadata value by key
+      # @overload metadata
+      #   @return [Hash] All metadata as key-value pairs
+      # @overload metadata(key)
+      #   @param key [String] The metadata key
+      #   @return [String, nil] The value or nil
+      def metadata(key = nil)
+        entries = metadata_entries || []
+        if key.nil?
+          # Return all metadata as hash
+          entries.each_with_object({}) { |e, h| h[e.key] = e.value }
+        else
+          # Return specific value
+          entries.find { |e| e.key == key }&.value
+        end
+      end
+
+      # Convenience method to set metadata
+      # @param key [String] The metadata key
+      # @param value [String] The value to set
+      def set_metadata(key, value)
+        self.metadata_entries ||= []
+        existing = metadata_entries.find { |e| e.key == key }
+        if existing
+          existing.value = value
+        else
+          metadata_entries << MetadataEntry.new(key: key, value: value)
+        end
+      end
+
+      # Get all element attributes as a hash, or a specific attribute value by name
+      # @overload attr
+      #   @return [Hash] All attributes as key-value pairs
+      # @overload attr(name)
+      #   @param name [String] The attribute name
+      #   @return [String, nil] The value or nil
+      def attr(name = nil)
+        attrs = element_attributes || []
+        if name.nil?
+          # Return all attributes as hash
+          attrs.each_with_object({}) { |a, h| h[a.name] = a.value }
+        else
+          # Return specific value
+          attrs.find { |a| a.name == name }&.value
+        end
+      end
+
+      # Set attribute value
+      # @param name [String] The attribute name
+      # @param value [String] The value to set
+      def set_attr(name, value)
+        self.element_attributes ||= []
+        existing = element_attributes.find { |a| a.name == name }
+        if existing
+          existing.value = value
+        else
+          element_attributes << ElementAttribute.new(name: name, value: value)
+        end
+      end
+
+      # Compare this model with another for semantic equivalence
+      #
+      # Semantic equivalence means the models represent the same semantic
+      # content, even if their exact structure differs. This is different
+      # from equality, which requires exact matching.
+      #
+      # @param other [Object] the object to compare with
+      # @return [Boolean] true if semantically equivalent, false otherwise
+      def semantically_equivalent?(other)
+        return false unless other.is_a?(self.class)
+
+        comparable_attributes.all? do |attr|
+          compare_attribute(attr, other)
+        end
+      end
+
+      # Accept a visitor to traverse this element
+      #
+      # Implements the visitor pattern for document traversal.
+      # The visitor's visit method will be called with this element.
+      #
+      # @param visitor [Coradoc::Visitor::Base] Visitor to accept
+      # @return [void]
+      def accept(visitor)
+        visitor.visit(self)
+      end
+
+      private
+
+      # List of attributes to compare for semantic equivalence
+      #
+      # Override in subclasses to define which attributes matter for
+      # equivalence. By default, only id and title are compared.
+      #
+      # @return [Array<Symbol>] list of attribute names to compare
+      def comparable_attributes
+        %i[id title]
+      end
+
+      # Compare a single attribute between this model and another
+      def compare_attribute(attr, other)
+        self_value = public_send(attr)
+        other_value = other.public_send(attr)
+
+        case self_value
+        when Array
+          compare_arrays(self_value, other_value)
+        when Base
+          self_value.semantically_equivalent?(other_value)
+        else
+          self_value == other_value
+        end
+      end
+
+      # Compare two arrays for semantic equivalence
+      def compare_arrays(arr1, arr2)
+        return false unless arr1.size == arr2.size
+
+        arr1.zip(arr2).all? do |item1, item2|
+          if item1.is_a?(Base)
+            item1.semantically_equivalent?(item2)
+          else
+            item1 == item2
+          end
+        end
+      end
+    end
+  end
+end