ace-support-markdown 0.3.0

data/lib/ace/support/markdown/atoms/frontmatter_serializer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Support
+    module Markdown
+      module Atoms
+        # Pure function to serialize frontmatter hash to YAML format
+        # Handles delimiter wrapping and YAML formatting
+        class FrontmatterSerializer
+          # Serialize frontmatter hash to YAML string with delimiters
+          # @param frontmatter [Hash] The frontmatter data
+          # @param body [String, nil] Optional body content to append
+          # @return [Hash] Result with :content (String), :valid (Boolean), :errors (Array)
+          def self.serialize(frontmatter, body: nil)
+            return empty_frontmatter_result if frontmatter.nil? || frontmatter.empty?
+
+            unless frontmatter.is_a?(Hash)
+              return {
+                content: "",
+                valid: false,
+                errors: ["Frontmatter must be a hash, got #{frontmatter.class}"]
+              }
+            end
+
+            begin
+              # Convert to YAML
+              yaml_content = YAML.dump(frontmatter).strip
+
+              # Remove leading --- that YAML.dump adds
+              yaml_content = yaml_content.sub(/^---\n/, "")
+
+              # Build the document
+              parts = ["---", yaml_content, "---"]
+
+              # Add body if provided
+              parts << "" << body.strip if body && !body.empty?
+
+              {
+                content: parts.join("\n"),
+                valid: true,
+                errors: []
+              }
+            rescue => e
+              {
+                content: "",
+                valid: false,
+                errors: ["YAML serialization error: #{e.message}"]
+              }
+            end
+          end
+
+          # Rebuild markdown document with frontmatter and body
+          # @param frontmatter [Hash] The frontmatter data
+          # @param body [String] The body content
+          # @return [String] The complete markdown document
+          def self.rebuild_document(frontmatter, body)
+            result = serialize(frontmatter, body: body)
+            raise ValidationError, result[:errors].join(", ") unless result[:valid]
+
+            result[:content]
+          end
+
+          # Serialize frontmatter only (without body)
+          # @param frontmatter [Hash] The frontmatter data
+          # @return [String] The frontmatter section with delimiters
+          def self.frontmatter_only(frontmatter)
+            result = serialize(frontmatter)
+            raise ValidationError, result[:errors].join(", ") unless result[:valid]
+
+            result[:content]
+          end
+
+          private
+
+          def self.empty_frontmatter_result
+            {
+              content: "---\n---",
+              valid: true,
+              errors: []
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/markdown/atoms/section_extractor.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Ace
+  module Support
+    module Markdown
+      module Atoms
+        # Pure function to extract sections from markdown using Kramdown AST
+        # Supports exact string matching for section headings (v0.1.0)
+        class SectionExtractor
+          # Extract a section by heading text (exact string match)
+          # @param content [String] The markdown content (without frontmatter)
+          # @param heading_text [String] The exact heading text to match (e.g., "References")
+          # @return [Hash] Result with :section_content (String), :found (Boolean), :errors (Array)
+          def self.extract(content, heading_text)
+            return empty_result("Empty content") if content.nil? || content.empty?
+            return empty_result("Heading text required") if heading_text.nil? || heading_text.empty?
+
+            begin
+              # Parse markdown with Kramdown
+              doc = Kramdown::Document.new(content, input: "GFM")
+
+              # Find the target header in the AST
+              target_header, target_index = find_header(doc.root.children, heading_text)
+
+              unless target_header
+                return {
+                  section_content: nil,
+                  found: false,
+                  errors: ["Section not found: #{heading_text}"]
+                }
+              end
+
+              # Extract content between this header and the next same-or-higher level header
+              section_content = extract_section_content(
+                doc.root.children,
+                target_index,
+                target_header.options[:level]
+              )
+
+              {
+                section_content: section_content,
+                found: true,
+                errors: []
+              }
+            rescue => e
+              {
+                section_content: nil,
+                found: false,
+                errors: ["Section extraction error: #{e.message}"]
+              }
+            end
+          end
+
+          # Extract all sections with their headings
+          # @param content [String] The markdown content
+          # @return [Array<Hash>] Array of {:heading, :level, :content}
+          def self.extract_all(content)
+            return [] if content.nil? || content.empty?
+
+            begin
+              doc = Kramdown::Document.new(content, input: "GFM")
+              headers = find_all_headers(doc.root.children)
+
+              headers.map.with_index do |header_info, idx|
+                # Extract content for each section
+                content_text = extract_section_content(
+                  doc.root.children,
+                  header_info[:index],
+                  header_info[:level]
+                )
+
+                {
+                  heading: header_info[:text],
+                  level: header_info[:level],
+                  content: content_text
+                }
+              end
+            rescue
+              []
+            end
+          end
+
+          private
+
+          # Find a header element by exact text match
+          def self.find_header(elements, heading_text)
+            elements.each_with_index do |el, idx|
+              next unless el.type == :header
+
+              # Extract text from header children
+              text = el.children
+                .select { |c| c.type == :text }
+                .map(&:value)
+                .join
+
+              return [el, idx] if text == heading_text
+            end
+
+            nil
+          end
+
+          # Find all headers in the document
+          def self.find_all_headers(elements)
+            headers = []
+
+            elements.each_with_index do |el, idx|
+              next unless el.type == :header
+
+              text = el.children
+                .select { |c| c.type == :text }
+                .map(&:value)
+                .join
+
+              headers << {
+                text: text,
+                level: el.options[:level],
+                index: idx
+              }
+            end
+
+            headers
+          end
+
+          # Extract content elements between a header and the next same-or-higher level header
+          def self.extract_section_content(elements, start_index, level)
+            content_elements = []
+
+            # Collect elements after the header until next same-or-higher level header
+            ((start_index + 1)...elements.length).each do |i|
+              el = elements[i]
+
+              # Stop if we hit another header of same or higher level
+              if el.type == :header && el.options[:level] <= level
+                break
+              end
+
+              content_elements << el
+            end
+
+            # Convert elements back to markdown
+            elements_to_markdown(content_elements)
+          end
+
+          # Convert Kramdown elements back to markdown string
+          def self.elements_to_markdown(elements)
+            return "" if elements.empty?
+
+            # Create a new document with these elements
+            temp_doc = Kramdown::Document.new("")
+            temp_root = temp_doc.root
+            temp_root.options[:encoding] = "UTF-8"
+
+            # Add elements to the new root
+            elements.each { |el| temp_root.children << el }
+
+            # Convert to markdown
+            temp_doc.to_kramdown.strip
+          end
+
+          def self.empty_result(error_message)
+            {
+              section_content: nil,
+              found: false,
+              errors: [error_message]
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/markdown/models/markdown_document.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Markdown
+      module Models
+        # Immutable representation of a markdown document
+        # Contains frontmatter and sections for safe transformations
+        class MarkdownDocument
+          attr_reader :frontmatter, :sections, :raw_body, :file_path
+
+          # Create a new MarkdownDocument
+          # @param frontmatter [Hash] The YAML frontmatter data
+          # @param raw_body [String] The raw body content (without frontmatter)
+          # @param sections [Array<Section>] Optional parsed sections
+          # @param file_path [String, nil] Optional source file path
+          def initialize(frontmatter:, raw_body:, sections: nil, file_path: nil)
+            @frontmatter = frontmatter.freeze
+            @raw_body = raw_body.freeze
+            @sections = sections&.freeze
+            @file_path = file_path&.freeze
+
+            validate!
+          end
+
+          # Create a new document with updated frontmatter
+          # @param updates [Hash] Frontmatter updates to merge
+          # @return [MarkdownDocument] New document instance
+          def with_frontmatter(updates)
+            new_frontmatter = @frontmatter.merge(updates)
+
+            MarkdownDocument.new(
+              frontmatter: new_frontmatter,
+              raw_body: @raw_body,
+              sections: @sections,
+              file_path: @file_path
+            )
+          end
+
+          # Create a new document with updated body
+          # @param new_body [String] The new body content
+          # @return [MarkdownDocument] New document instance
+          def with_body(new_body)
+            MarkdownDocument.new(
+              frontmatter: @frontmatter,
+              raw_body: new_body,
+              sections: nil, # Invalidate sections cache
+              file_path: @file_path
+            )
+          end
+
+          # Create a new document with updated sections
+          # @param new_sections [Array<Section>] The new sections
+          # @return [MarkdownDocument] New document instance
+          def with_sections(new_sections)
+            # Rebuild raw_body from sections
+            new_body = new_sections.map(&:to_markdown).join("\n\n")
+
+            MarkdownDocument.new(
+              frontmatter: @frontmatter,
+              raw_body: new_body,
+              sections: new_sections,
+              file_path: @file_path
+            )
+          end
+
+          # Get a specific frontmatter field
+          # @param key [String, Symbol] The field key
+          # @return [Object, nil] The field value
+          def get_frontmatter(key)
+            @frontmatter[key.to_s] || @frontmatter[key.to_sym]
+          end
+
+          # Find a section by heading text
+          # @param heading [String] The heading to find
+          # @return [Section, nil]
+          def find_section(heading)
+            return nil unless @sections
+
+            @sections.find { |s| s.heading == heading }
+          end
+
+          # Convert document to complete markdown string
+          # @return [String] The complete markdown document
+          def to_markdown
+            Atoms::FrontmatterSerializer.rebuild_document(@frontmatter, @raw_body)
+          end
+
+          # Check if document has frontmatter
+          # @return [Boolean]
+          def has_frontmatter?
+            !@frontmatter.empty?
+          end
+
+          # Check if document has sections parsed
+          # @return [Boolean]
+          def has_sections?
+            !@sections.nil? && !@sections.empty?
+          end
+
+          # Get document statistics
+          # @return [Hash]
+          def stats
+            {
+              frontmatter_fields: @frontmatter.keys.length,
+              body_length: @raw_body.length,
+              sections_count: @sections&.length || 0,
+              word_count: @raw_body.split(/\s+/).length
+            }
+          end
+
+          # Compare documents for equality
+          # @param other [MarkdownDocument]
+          # @return [Boolean]
+          def ==(other)
+            other.is_a?(MarkdownDocument) &&
+              @frontmatter == other.frontmatter &&
+              @raw_body == other.raw_body
+          end
+
+          # Hash representation
+          # @return [Hash]
+          def to_h
+            {
+              frontmatter: @frontmatter,
+              raw_body: @raw_body,
+              sections: @sections&.map(&:to_h),
+              file_path: @file_path,
+              stats: stats
+            }
+          end
+
+          # Parse document from markdown string
+          # @param content [String] The complete markdown content
+          # @param file_path [String, nil] Optional source file path
+          # @return [MarkdownDocument]
+          def self.parse(content, file_path: nil)
+            result = Atoms::FrontmatterExtractor.extract(content)
+
+            raise ValidationError, result[:errors].join(", ") unless result[:valid]
+
+            new(
+              frontmatter: result[:frontmatter],
+              raw_body: result[:body],
+              file_path: file_path
+            )
+          end
+
+          # Parse document with sections
+          # @param content [String] The complete markdown content
+          # @param file_path [String, nil] Optional source file path
+          # @return [MarkdownDocument]
+          def self.parse_with_sections(content, file_path: nil)
+            doc = parse(content, file_path: file_path)
+
+            # Extract all sections
+            section_data = Atoms::SectionExtractor.extract_all(doc.raw_body)
+
+            sections = section_data.map do |s|
+              Section.new(
+                heading: s[:heading],
+                level: s[:level],
+                content: s[:content] || ""
+              )
+            end
+
+            doc.with_sections(sections)
+          end
+
+          private
+
+          def validate!
+            raise ArgumentError, "Frontmatter must be a hash" unless @frontmatter.is_a?(Hash)
+            raise ArgumentError, "Raw body cannot be nil" if @raw_body.nil?
+
+            if @sections
+              raise ArgumentError, "Sections must be an array" unless @sections.is_a?(Array)
+              unless @sections.all? { |s| s.is_a?(Section) }
+                raise ArgumentError, "All sections must be Section instances"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/markdown/models/section.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Markdown
+      module Models
+        # Immutable representation of a markdown section
+        # Contains heading information and content
+        class Section
+          attr_reader :heading, :level, :content, :metadata
+
+          # Create a new Section
+          # @param heading [String] The section heading text
+          # @param level [Integer] The heading level (1-6)
+          # @param content [String] The section content (without heading)
+          # @param metadata [Hash] Optional metadata about the section
+          def initialize(heading:, level:, content:, metadata: {})
+            @heading = heading.freeze
+            @level = level.freeze
+            @content = content.freeze
+            @metadata = metadata.freeze
+
+            validate!
+          end
+
+          # Create a new Section with updated content
+          # @param new_content [String] The new content
+          # @return [Section] New Section instance
+          def with_content(new_content)
+            Section.new(
+              heading: @heading,
+              level: @level,
+              content: new_content,
+              metadata: @metadata
+            )
+          end
+
+          # Create a new Section with updated heading
+          # @param new_heading [String] The new heading
+          # @return [Section] New Section instance
+          def with_heading(new_heading)
+            Section.new(
+              heading: new_heading,
+              level: @level,
+              content: @content,
+              metadata: @metadata
+            )
+          end
+
+          # Create a new Section with updated metadata
+          # @param new_metadata [Hash] The new metadata
+          # @return [Section] New Section instance
+          def with_metadata(new_metadata)
+            Section.new(
+              heading: @heading,
+              level: @level,
+              content: @content,
+              metadata: new_metadata
+            )
+          end
+
+          # Convert section to markdown string
+          # @return [String] The complete section as markdown
+          def to_markdown
+            heading_prefix = "#" * @level
+            "#{heading_prefix} #{@heading}\n\n#{@content}"
+          end
+
+          # Check if section is empty (no content)
+          # @return [Boolean]
+          def empty?
+            @content.nil? || @content.strip.empty?
+          end
+
+          # Get word count of section content
+          # @return [Integer]
+          def word_count
+            @content.split(/\s+/).length
+          end
+
+          # Compare sections for equality
+          # @param other [Section]
+          # @return [Boolean]
+          def ==(other)
+            other.is_a?(Section) &&
+              @heading == other.heading &&
+              @level == other.level &&
+              @content == other.content
+          end
+
+          # Hash representation
+          # @return [Hash]
+          def to_h
+            {
+              heading: @heading,
+              level: @level,
+              content: @content,
+              metadata: @metadata
+            }
+          end
+
+          private
+
+          def validate!
+            raise ArgumentError, "Heading cannot be nil or empty" if @heading.nil? || @heading.empty?
+            raise ArgumentError, "Level must be between 1 and 6" unless (1..6).cover?(@level)
+            raise ArgumentError, "Content cannot be nil" if @content.nil?
+            raise ArgumentError, "Metadata must be a hash" unless @metadata.is_a?(Hash)
+          end
+        end
+      end
+    end
+  end
+end