coradoc 1.1.8 → 2.0.12

data/lib/coradoc/document_builder.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Coradoc
+  class DocumentBuilder
+    attr_reader :document
+
+    def self.build(&block)
+      builder = new
+      builder.instance_eval(&block) if block_given?
+      builder
+    end
+
+    def initialize
+      @document = CoreModel::DocumentElement.new(
+        children: []
+      )
+      @current_context = @document
+      @context_stack = []
+    end
+
+    def title(text)
+      @document.title = text
+      self
+    end
+
+    def section(title_text, level: 1, &block)
+      new_section = CoreModel::SectionElement.new(
+        level: level,
+        title: title_text,
+        children: []
+      )
+
+      @current_context.children << new_section
+
+      if block_given?
+        push_context(new_section)
+        instance_eval(&block)
+        pop_context
+      end
+
+      self
+    end
+
+    def paragraph(text)
+      @current_context.children << CoreModel::ParagraphBlock.new(
+        content: text
+      )
+      self
+    end
+
+    def code(code_text, language: nil)
+      @current_context.children << CoreModel::SourceBlock.new(
+        content: code_text,
+        language: language
+      )
+      self
+    end
+
+    def blockquote(text, attribution: nil)
+      block = CoreModel::QuoteBlock.new(
+        content: text,
+        attribution: attribution
+      )
+      @current_context.children << block
+      self
+    end
+
+    def list(type = :unordered, &block)
+      list_items = []
+      list_type = type
+
+      wrapper = Object.new
+      wrapper.define_singleton_method(:item) do |text|
+        marker = list_type == :ordered ? '1.' : '*'
+        list_items << CoreModel::ListItem.new(content: text, marker: marker)
+        wrapper
+      end
+
+      wrapper.instance_eval(&block) if block_given?
+
+      @current_context.children << CoreModel::ListBlock.new(
+        marker_type: type.to_s,
+        items: list_items
+      )
+      self
+    end
+
+    alias ordered_list list
+    alias unordered_list list
+
+    def bulleted_list(&block)
+      list(:unordered, &block)
+    end
+
+    def numbered_list(&block)
+      list(:ordered, &block)
+    end
+
+    def image(src, alt: '', title: nil)
+      img = CoreModel::Image.new(src: src, alt: alt)
+      img.title = title if title
+      @current_context.children << img
+      self
+    end
+
+    def table(headers = [], rows = [])
+      table_rows = []
+
+      if headers.any?
+        header_cells = headers.map { |h| CoreModel::TableCell.new(content: h, header: true) }
+        table_rows << CoreModel::TableRow.new(cells: header_cells)
+      end
+
+      rows.each do |row|
+        cells = row.map { |c| CoreModel::TableCell.new(content: c.to_s) }
+        table_rows << CoreModel::TableRow.new(cells: cells)
+      end
+
+      @current_context.children << CoreModel::Table.new(rows: table_rows)
+      self
+    end
+
+    def hr
+      @current_context.children << CoreModel::HorizontalRuleBlock.new
+      self
+    end
+
+    def text(text_content)
+      @current_context.children << CoreModel::Block.new(
+        content: text_content
+      )
+      self
+    end
+
+    def admonition(type, text)
+      @current_context.children << CoreModel::AnnotationBlock.new(
+        annotation_type: type.to_s,
+        content: text
+      )
+      self
+    end
+
+    %i[note warning tip important caution].each do |admonition_type|
+      define_method(admonition_type) do |text|
+        admonition(admonition_type, text)
+      end
+    end
+
+    def to_core
+      @document
+    end
+
+    def to(format, **options)
+      Coradoc.serialize(@document, to: format, **options)
+    end
+
+    def to_html(**options)
+      to(:html, **options)
+    end
+
+    def to_markdown(**options)
+      to(:markdown, **options)
+    end
+
+    def to_asciidoc(**options)
+      to(:asciidoc, **options)
+    end
+
+    private
+
+    def push_context(new_context)
+      @context_stack << @current_context
+      @current_context = new_context
+    end
+
+    def pop_context
+      @current_context = @context_stack.pop
+    end
+  end
+
+  def self.build(&block)
+    DocumentBuilder.build(&block)
+  end
+end

data/lib/coradoc/document_manipulator.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Coradoc
+  class DocumentManipulator
+    attr_reader :document
+
+    def initialize(document)
+      unless document.is_a?(Coradoc::CoreModel::Base)
+        raise ArgumentError,
+              "Expected CoreModel::Base, got #{document.class}"
+      end
+
+      @document = document
+    end
+
+    def query(selector)
+      Coradoc::Query.query(@document, selector).to_a
+    end
+
+    def select_sections(level: nil, title: nil)
+      filtered = filter_sections(@document, level: level, title: title)
+      DocumentManipulator.new(filtered)
+    end
+
+    def transform_text
+      return self unless block_given?
+
+      Visitor::Transformer.new do |element|
+        case element
+        when CoreModel::InlineElement
+          element.content = yield(element.content) if element.content.is_a?(String)
+        when CoreModel::Block
+          element.content = yield(element.content) if element.content.is_a?(String)
+        end
+      end.visit(@document)
+      self
+    end
+
+    def transform_headings
+      return self unless block_given?
+
+      Visitor::Transformer.new do |element|
+        element.title = yield(element.title) if element.is_a?(CoreModel::StructuralElement) && element.title.is_a?(String)
+      end.visit(@document)
+      self
+    end
+
+    def add_toc(levels: 3, position: :top)
+      sections = collect_sections(@document, max_level: levels)
+      toc = CoreModel::TocGenerator.generate(sections)
+
+      toc_element = CoreModel::Block.new(block_semantic_type: 'toc', content: toc)
+      case position
+      when :top
+        @document.children = [toc_element] + @document.children
+      when :bottom
+        @document.children = @document.children + [toc_element]
+      end
+
+      self
+    end
+
+    def remove_elements(element_type)
+      Visitor::Transformer.new do |element|
+        next unless element.is_a?(CoreModel::StructuralElement) && element.children
+
+        element.children.reject! do |child|
+          match_element_type?(child, element_type)
+        end
+      end.visit(@document)
+      self
+    end
+
+    def add_metadata(metadata)
+      metadata.each do |key, value|
+        @document.set_metadata(key.to_s, value.to_s)
+      end
+      self
+    end
+
+    def set_title(title)
+      @document.title = title
+      self
+    end
+
+    def set_id(id)
+      @document.id = id
+      self
+    end
+
+    def to_html(**options)
+      Coradoc.serialize(@document, to: :html, **options)
+    end
+
+    def to_markdown(**options)
+      Coradoc.serialize(@document, to: :markdown, **options)
+    end
+
+    def to_asciidoc(**options)
+      Coradoc.serialize(@document, to: :asciidoc, **options)
+    end
+
+    def to(format, **options)
+      Coradoc.serialize(@document, to: format, **options)
+    end
+
+    def to_core
+      @document
+    end
+
+    def clone
+      DocumentManipulator.new(deep_clone(@document))
+    end
+
+    private
+
+    def match_element_type?(child, element_type)
+      return false unless child.is_a?(CoreModel::Block)
+
+      case element_type
+      when :comment_line, :comment_block
+        child.is_a?(CoreModel::CommentBlock)
+      else
+        child.resolve_semantic_type == element_type.to_sym
+      end
+    end
+
+    def filter_sections(element, level: nil, title: nil)
+      if element.is_a?(CoreModel::StructuralElement) && element.children
+        element.children = element.children
+                                  .map { |child| filter_sections(child, level: level, title: title) }
+                                  .compact
+      end
+
+      return nil if element.is_a?(CoreModel::StructuralElement) && element.section? && !element.document? && !section_matches?(
+        element, level: level, title: title
+      )
+
+      element
+    end
+
+    def section_matches?(section, level: nil, title: nil)
+      if level
+        element_level = section.heading_level
+        case level
+        when Range then return false unless level.include?(element_level)
+        when Integer then return false unless element_level == level
+        end
+      end
+
+      if title
+        element_title = section.title || ''
+        case title
+        when String then return false unless element_title.include?(title)
+        when Regexp then return false unless element_title&.match?(title)
+        end
+      end
+
+      true
+    end
+
+    def collect_sections(element, max_level: 3, current_level: 1)
+      sections = []
+      return sections unless element.is_a?(CoreModel::StructuralElement)
+
+      element.children.each do |child|
+        next unless child.is_a?(CoreModel::StructuralElement) &&
+                    child.section? && (current_level <= max_level)
+
+        sections << {
+          id: child.id,
+          title: child.title,
+          level: child.level || current_level,
+          children: collect_sections(child, max_level: max_level,
+                                            current_level: current_level + 1)
+        }
+      end
+
+      sections
+    end
+
+    def deep_clone(element)
+      case element
+      when CoreModel::Base
+        cloned = element.class.new
+        element.class.attributes.each_key do |name|
+          cloned.public_send("#{name}=", deep_clone(element.public_send(name)))
+        end
+        cloned
+      when Array
+        element.map { |item| deep_clone(item) }
+      when Hash
+        element.transform_values { |v| deep_clone(v) }
+      else
+        begin
+          element.dup
+        rescue StandardError
+          element
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/errors.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Base error class for all Coradoc errors
+  class Error < StandardError; end
+
+  # Suggestion patterns for common parsing errors
+  #
+  # These patterns are matched against error messages and source content
+  # to provide helpful suggestions for fixing common issues.
+  ERROR_SUGGESTIONS = [
+    {
+      pattern: /unterminated.*string|unexpected.*end.*of.*input|expected.*["']/i,
+      suggestion: 'Check for unclosed quotes or strings',
+      examples: ["'text'", '"text"']
+    },
+    {
+      pattern: /unexpected.*indentation|indentation.*error|inconsistent.*indent/i,
+      suggestion: 'Check indentation - use consistent spaces or tabs',
+      examples: ['  indented line', '    nested item']
+    },
+    {
+      pattern: /missing.*separator|expected.*delimiter|missing.*comma/i,
+      suggestion: 'Add missing separator between elements',
+      examples: ['item1, item2', 'key: value']
+    },
+    {
+      pattern: /invalid.*attribute|unknown.*attribute|attribute.*not.*allowed/i,
+      suggestion: 'Check attribute spelling and allowed values',
+      examples: ['[role=example]', '[source,ruby]']
+    },
+    {
+      pattern: /invalid.*heading|heading.*level|expected.*heading/i,
+      suggestion: 'Use valid heading syntax with = or # markers',
+      examples: ['= Level 1', '== Level 2', '### Level 3']
+    },
+    {
+      pattern: /invalid.*list|list.*marker|expected.*list.*item/i,
+      suggestion: 'Use correct list markers (*, -, ., or numbered)',
+      examples: ['* bullet', '. ordered', 'term:: definition']
+    },
+    {
+      pattern: /invalid.*link|malformed.*url|link.*syntax/i,
+      suggestion: 'Use correct link syntax: text[url] or link:url[]',
+      examples: ['Google[https://google.com]', 'link:file.adoc[]']
+    },
+    {
+      pattern: /invalid.*table|table.*delimiter|expected.*separator/i,
+      suggestion: 'Check table syntax with | delimiters',
+      examples: ["|===\n| Cell 1 | Cell 2\n|==="]
+    },
+    {
+      pattern: /invalid.*block|block.*delimiter|unterminated.*block/i,
+      suggestion: 'Ensure block delimiters match (----, ****, ====, etc.)',
+      examples: ["----\ncode\n----", "====\nexample\n===="]
+    },
+    {
+      pattern: /invalid.*macro|unknown.*macro|macro.*syntax/i,
+      suggestion: 'Check macro syntax: name:target[attributes]',
+      examples: ['include::file.adoc[]', 'image::image.png[]']
+    }
+  ].freeze
+
+  # Enhanced error classes with source context support
+  #
+  # These error classes provide additional context such as line numbers,
+  # column positions, source snippets, and suggestions to help users debug issues.
+  #
+  # @example Raising a parse error with context
+  #   raise ParseError.new(
+  #     "Unexpected token",
+  #     source: content,
+  #     line: 10,
+  #     column: 5
+  #   )
+  #
+  # @example Handling errors with context
+  #   begin
+  #     Coradoc.parse(text, format: :markdown)
+  #   rescue Coradoc::ParseError => e
+  #     puts e.message_with_context
+  #     puts e.suggestion if e.suggestion
+  #   end
+  #
+  class ParseError < Error
+    attr_reader :source, :line, :column, :snippet_lines, :suggestion
+
+    # Create a new parse error with optional source context
+    #
+    # @param message [String] The error message
+    # @param source [String, nil] The source text being parsed
+    # @param line [Integer, nil] The line number (1-indexed)
+    # @param column [Integer, nil] The column number (1-indexed)
+    # @param snippet_lines [Integer] Number of context lines to show (default: 3)
+    # @param suggestion [String, nil] Optional suggestion for fixing the error
+    def initialize(message, source: nil, line: nil, column: nil, snippet_lines: 3,
+                   suggestion: nil)
+      @source = source
+      @line = line
+      @column = column
+      @snippet_lines = snippet_lines
+      @suggestion = suggestion || find_suggestion(message, source, line)
+      super(build_message(message))
+    end
+
+    # Returns the error message with full context
+    #
+    # @return [String] Formatted error message with source snippet
+    def message_with_context
+      return message unless source && line
+
+      msg = message
+      msg += "\n\n"
+      msg += source_snippet
+      if suggestion
+        msg += "\n\n"
+        msg += "Suggestion: #{suggestion}"
+      end
+      msg
+    end
+
+    # Returns the source snippet around the error location
+    #
+    # @return [String] Formatted source snippet with line numbers
+    def source_snippet
+      return '' unless source && line
+
+      lines = source.lines
+      start_line = [1, line - snippet_lines].max
+      end_line = [lines.length, line + snippet_lines].min
+
+      snippet = []
+      (start_line..end_line).each do |i|
+        prefix = i == line ? '>>> ' : '    '
+        snippet_line = lines[i - 1]&.chomp || ''
+        snippet << "#{prefix}#{i.to_s.rjust(4)}: #{snippet_line}"
+
+        # Add column indicator on the error line
+        if i == line && column
+          indicator = "#{' ' * (prefix.length + 6 + column - 1)}^"
+          snippet << indicator
+        end
+      end
+
+      snippet.join("\n")
+    end
+
+    # Returns all suggestions that match this error
+    #
+    # @return [Array<String>] List of applicable suggestions
+    def all_suggestions
+      return [] unless message || source
+
+      suggestions = []
+      ERROR_SUGGESTIONS.each do |entry|
+        suggestions << format_suggestion(entry) if entry[:pattern].match?(message)
+      end
+
+      # Also check source line if available
+      if source && line
+        source_line = source.lines[line - 1]
+        if source_line
+          ERROR_SUGGESTIONS.each do |entry|
+            suggestions << format_suggestion(entry) if entry[:pattern].match?(source_line)
+          end
+        end
+      end
+
+      suggestions.uniq
+    end
+
+    private
+
+    def build_message(message)
+      context = []
+      context << "line #{line}" if line
+      context << "column #{column}" if column
+
+      if context.any?
+        "#{message} (at #{context.join(', ')})"
+      else
+        message
+      end
+    end
+
+    def find_suggestion(message, source, line)
+      return nil unless message || source
+
+      # Check message against patterns
+      ERROR_SUGGESTIONS.each do |entry|
+        return format_suggestion(entry) if entry[:pattern].match?(message)
+      end
+
+      # Check source line if available
+      if source && line
+        source_line = source.lines[line - 1]
+        if source_line
+          ERROR_SUGGESTIONS.each do |entry|
+            return format_suggestion(entry) if entry[:pattern].match?(source_line)
+          end
+        end
+      end
+
+      nil
+    end
+
+    def format_suggestion(entry)
+      result = entry[:suggestion]
+      result += " (e.g., #{entry[:examples].first(2).join(', ')})" if entry[:examples]&.any?
+      result
+    end
+  end
+
+  # Error raised when validation fails
+  #
+  # @example
+  #   raise ValidationError.new(
+  #     "Invalid document structure",
+  #     errors: ["Missing title", "Empty section"]
+  #   )
+  #
+  class ValidationError < Error
+    attr_reader :errors
+
+    # Create a new validation error
+    #
+    # @param message [String] The error message
+    # @param errors [Array<String>] List of specific validation errors
+    def initialize(message, errors: [])
+      @errors = errors
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(message)
+      return message if errors.empty?
+
+      "#{message}\n  - #{errors.join("\n  - ")}"
+    end
+  end
+
+  # Error raised when transformation fails
+  #
+  # @example
+  #   raise TransformationError.new(
+  #     "Cannot convert element",
+  #     source_type: "Paragraph",
+  #     target_type: "CoreModel::Block"
+  #   )
+  #
+  class TransformationError < Error
+    attr_reader :source_type, :target_type
+
+    # Create a new transformation error
+    #
+    # @param message [String] The error message
+    # @param source_type [String, Class, nil] The source type being transformed
+    # @param target_type [String, Class, nil] The target type
+    def initialize(message, source_type: nil, target_type: nil)
+      @source_type = source_type
+      @target_type = target_type
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(message)
+      parts = [message]
+      parts << "source: #{source_type}" if source_type
+      parts << "target: #{target_type}" if target_type
+      parts.join(' (') + (parts.length > 1 ? ')' : '')
+    end
+  end
+
+  # Error raised when a file is not found
+  class FileNotFoundError < Error
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+      super("File not found: #{path}")
+    end
+  end
+
+  # Error raised when a requested format is not supported
+  #
+  # @example
+  #   raise UnsupportedFormatError.new(:docx, available: [:html, :markdown])
+  #
+  class UnsupportedFormatError < Error
+    attr_reader :requested_format, :available_formats
+
+    # Create a new unsupported format error
+    #
+    # @param format [Symbol, String] The requested format
+    # @param available [Array<Symbol>] List of available formats
+    def initialize(format, available: [])
+      @requested_format = format
+      @available_formats = available
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      msg = "Format '#{requested_format}' is not supported"
+      msg += ". Available formats: #{available_formats.join(', ')}" if available_formats.any?
+      msg
+    end
+  end
+end