ace-support-markdown 0.3.0

data/lib/ace/support/markdown/molecules/document_builder.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Markdown
+      module Molecules
+        # Build markdown documents programmatically
+        # Provides fluent API for creating documents from scratch
+        class DocumentBuilder
+          attr_reader :frontmatter, :sections
+
+          def initialize
+            @frontmatter = {}
+            @sections = []
+          end
+
+          # Set frontmatter fields
+          # @param data [Hash] Frontmatter data
+          # @return [DocumentBuilder] self for chaining
+          def frontmatter(data)
+            raise ArgumentError, "Frontmatter must be a hash" unless data.is_a?(Hash)
+
+            @frontmatter = @frontmatter.merge(data)
+            self
+          end
+
+          # Set a single frontmatter field
+          # @param key [String, Symbol] The field key
+          # @param value [Object] The field value
+          # @return [DocumentBuilder] self for chaining
+          def set_field(key, value)
+            @frontmatter[key.to_s] = value
+            self
+          end
+
+          # Add a section
+          # @param heading [String] The section heading
+          # @param content [String] The section content
+          # @param level [Integer] The heading level (default: 2)
+          # @return [DocumentBuilder] self for chaining
+          def add_section(heading:, content:, level: 2)
+            section = Models::Section.new(
+              heading: heading,
+              level: level,
+              content: content
+            )
+
+            @sections << section
+            self
+          end
+
+          # Add a title (level 1 heading)
+          # @param title [String] The title text
+          # @param content [String] Content under the title
+          # @return [DocumentBuilder] self for chaining
+          def title(title, content: "")
+            add_section(heading: title, content: content, level: 1)
+          end
+
+          # Add raw body content (without sections)
+          # @param content [String] The body content
+          # @return [DocumentBuilder] self for chaining
+          def body(content)
+            @body_content = content
+            self
+          end
+
+          # Build the document as a MarkdownDocument model
+          # @return [MarkdownDocument]
+          def build
+            body_text = if @sections.any?
+              # Build from sections
+              @sections.map(&:to_markdown).join("\n\n")
+            else
+              # Use raw body content
+              @body_content || ""
+            end
+
+            Models::MarkdownDocument.new(
+              frontmatter: @frontmatter,
+              raw_body: body_text,
+              sections: @sections.any? ? @sections : nil
+            )
+          end
+
+          # Build and convert to markdown string
+          # @return [String]
+          def to_markdown
+            build.to_markdown
+          end
+
+          # Validate the current builder state
+          # @return [Hash] Result with :valid, :errors
+          def validate
+            errors = []
+
+            if @frontmatter.empty?
+              errors << "No frontmatter defined"
+            end
+
+            if @sections.empty? && (@body_content.nil? || @body_content.empty?)
+              errors << "No content defined (neither sections nor body)"
+            end
+
+            {
+              valid: errors.empty?,
+              errors: errors
+            }
+          end
+
+          # Check if builder is valid
+          # @return [Boolean]
+          def valid?
+            validate[:valid]
+          end
+
+          # Create a builder from an existing document
+          # @param document [MarkdownDocument] The source document
+          # @return [DocumentBuilder]
+          def self.from_document(document)
+            raise ArgumentError, "Document must be a MarkdownDocument" unless document.is_a?(Models::MarkdownDocument)
+
+            builder = new
+            builder.frontmatter(document.frontmatter)
+
+            if document.has_sections?
+              document.sections.each do |section|
+                builder.add_section(
+                  heading: section.heading,
+                  content: section.content,
+                  level: section.level
+                )
+              end
+            else
+              builder.body(document.raw_body)
+            end
+
+            builder
+          end
+
+          # Create a minimal document with just frontmatter
+          # @param frontmatter [Hash] The frontmatter data
+          # @return [MarkdownDocument]
+          def self.minimal(frontmatter)
+            new.frontmatter(frontmatter).build
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/markdown/molecules/frontmatter_editor.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Ace
+  module Support
+    module Markdown
+      module Molecules
+        # Atomic frontmatter field updates for markdown documents
+        # Handles nested keys, special values, and immutable transformations
+        class FrontmatterEditor
+          # Update frontmatter fields in a document
+          # @param document [MarkdownDocument] The document to update
+          # @param updates [Hash] Fields to update (supports nested keys with dots)
+          # @return [MarkdownDocument] New document with updated frontmatter
+          def self.update(document, updates)
+            raise ArgumentError, "Document must be a MarkdownDocument" unless document.is_a?(Models::MarkdownDocument)
+            raise ArgumentError, "Updates must be a hash" unless updates.is_a?(Hash)
+
+            updated_frontmatter = apply_updates(document.frontmatter.dup, updates)
+
+            document.with_frontmatter(updated_frontmatter)
+          end
+
+          # Update a single field
+          # @param document [MarkdownDocument] The document to update
+          # @param key [String] The field key (supports dots for nesting)
+          # @param value [Object] The new value
+          # @return [MarkdownDocument] New document with updated field
+          def self.update_field(document, key, value)
+            update(document, {key => value})
+          end
+
+          # Delete a field from frontmatter
+          # @param document [MarkdownDocument] The document to update
+          # @param key [String] The field key to delete
+          # @return [MarkdownDocument] New document with field removed
+          def self.delete_field(document, key)
+            updated_frontmatter = document.frontmatter.dup
+            updated_frontmatter.delete(key)
+            updated_frontmatter.delete(key.to_sym) if key.is_a?(String)
+
+            document.with_frontmatter(updated_frontmatter)
+          end
+
+          # Merge multiple updates atomically
+          # @param document [MarkdownDocument] The document to update
+          # @param updates_list [Array<Hash>] List of update hashes
+          # @return [MarkdownDocument] New document with all updates applied
+          def self.merge_updates(document, updates_list)
+            raise ArgumentError, "Updates list must be an array" unless updates_list.is_a?(Array)
+
+            updates_list.reduce(document) do |doc, updates|
+              update(doc, updates)
+            end
+          end
+
+          private
+
+          # Apply updates to frontmatter hash (mutable operation on copy)
+          def self.apply_updates(frontmatter, updates)
+            updates.each do |key, value|
+              key_str = key.to_s
+
+              # Handle nested keys with dots (e.g., "update.last-updated")
+              if key_str.include?(".")
+                apply_nested_update(frontmatter, key_str, value)
+              else
+                frontmatter[key_str] = process_value(value)
+              end
+            end
+
+            frontmatter
+          end
+
+          # Apply update to nested key path
+          def self.apply_nested_update(frontmatter, key_path, value)
+            parts = key_path.split(".")
+            target = frontmatter
+
+            # Navigate to the target hash
+            parts[0...-1].each do |part|
+              target[part] ||= {}
+              target = target[part]
+            end
+
+            # Set the final value
+            target[parts.last] = process_value(value)
+          end
+
+          # Process special values before setting
+          def self.process_value(value)
+            case value
+            when "today"
+              Date.today.strftime("%Y-%m-%d")
+            when "now"
+              Time.now.strftime("%Y-%m-%d %H:%M:%S")
+            when /^\d{4}-\d{2}-\d{2}$/
+              value # Already a date string
+            else
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/markdown/molecules/kramdown_processor.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Ace
+  module Support
+    module Markdown
+      module Molecules
+        # Parse and serialize markdown using Kramdown
+        # Provides GFM-compatible markdown processing
+        class KramdownProcessor
+          # Parse markdown content to AST
+          # @param content [String] The markdown content
+          # @param options [Hash] Kramdown options
+          # @return [Hash] Result with :document, :success, :errors
+          def self.parse(content, options: {})
+            default_options = {
+              input: "GFM", # GitHub Flavored Markdown
+              hard_wrap: false,
+              auto_ids: true,
+              parse_block_html: true
+            }
+
+            merged_options = default_options.merge(options)
+
+            begin
+              document = Kramdown::Document.new(content, merged_options)
+
+              {
+                document: document,
+                success: true,
+                warnings: document.warnings || [],
+                errors: []
+              }
+            rescue => e
+              {
+                document: nil,
+                success: false,
+                warnings: [],
+                errors: ["Kramdown parsing error: #{e.message}"]
+              }
+            end
+          end
+
+          # Convert markdown AST back to markdown string
+          # @param document [Kramdown::Document] The kramdown document
+          # @return [Hash] Result with :markdown, :success, :errors
+          def self.to_markdown(document)
+            raise ArgumentError, "Document must be a Kramdown::Document" unless document.is_a?(Kramdown::Document)
+
+            begin
+              markdown = document.to_kramdown
+
+              {
+                markdown: markdown,
+                success: true,
+                errors: []
+              }
+            rescue => e
+              {
+                markdown: nil,
+                success: false,
+                errors: ["Kramdown serialization error: #{e.message}"]
+              }
+            end
+          end
+
+          # Round-trip: parse and convert back to markdown
+          # @param content [String] The markdown content
+          # @param options [Hash] Kramdown options
+          # @return [Hash] Result with :markdown, :success, :errors
+          def self.round_trip(content, options: {})
+            parse_result = parse(content, options: options)
+            return parse_result unless parse_result[:success]
+
+            to_markdown(parse_result[:document])
+          end
+
+          # Validate markdown can be parsed without errors
+          # @param content [String] The markdown content
+          # @return [Boolean] true if valid
+          def self.valid?(content)
+            result = parse(content)
+            result[:success] && result[:errors].empty?
+          end
+
+          # Extract headings from markdown
+          # @param content [String] The markdown content
+          # @return [Array<Hash>] Array of {:text, :level}
+          def self.extract_headings(content)
+            result = parse(content)
+            return [] unless result[:success]
+
+            find_headings(result[:document].root)
+          end
+
+          private
+
+          # Recursively find all headings in AST
+          def self.find_headings(element, headings = [])
+            if element.type == :header
+              text = element.children
+                .select { |c| c.type == :text }
+                .map(&:value)
+                .join
+
+              headings << {
+                text: text,
+                level: element.options[:level]
+              }
+            end
+
+            element.children.each do |child|
+              find_headings(child, headings)
+            end
+
+            headings
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/markdown/molecules/section_editor.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Markdown
+      module Molecules
+        # Edit document sections by heading
+        # Supports replace, append, delete operations using exact string matching
+        class SectionEditor
+          # Replace a section's content by heading
+          # @param document [MarkdownDocument] The document to update
+          # @param heading [String] The exact heading text to match
+          # @param new_content [String] The replacement content
+          # @return [MarkdownDocument] New document with replaced section
+          def self.replace_section(document, heading, new_content)
+            raise ArgumentError, "Document must be a MarkdownDocument" unless document.is_a?(Models::MarkdownDocument)
+
+            # Extract the current section to get its level
+            section_result = Atoms::SectionExtractor.extract(document.raw_body, heading)
+
+            unless section_result[:found]
+              raise SectionNotFoundError, "Section not found: #{heading}"
+            end
+
+            # Parse all sections
+            all_sections = Atoms::SectionExtractor.extract_all(document.raw_body)
+
+            # Find and replace the target section
+            new_sections = all_sections.map do |s|
+              if s[:heading] == heading
+                Models::Section.new(
+                  heading: s[:heading],
+                  level: s[:level],
+                  content: new_content
+                )
+              else
+                Models::Section.new(
+                  heading: s[:heading],
+                  level: s[:level],
+                  content: s[:content] || ""
+                )
+              end
+            end
+
+            document.with_sections(new_sections)
+          end
+
+          # Append content to a section
+          # @param document [MarkdownDocument] The document to update
+          # @param heading [String] The exact heading text to match
+          # @param additional_content [String] Content to append
+          # @return [MarkdownDocument] New document with updated section
+          def self.append_to_section(document, heading, additional_content)
+            raise ArgumentError, "Document must be a MarkdownDocument" unless document.is_a?(Models::MarkdownDocument)
+
+            # Extract current section
+            section_result = Atoms::SectionExtractor.extract(document.raw_body, heading)
+
+            unless section_result[:found]
+              raise SectionNotFoundError, "Section not found: #{heading}"
+            end
+
+            # Combine existing and new content
+            existing_content = section_result[:section_content] || ""
+            separator = existing_content.empty? ? "" : "\n\n"
+            new_content = "#{existing_content}#{separator}#{additional_content}"
+
+            # Replace with combined content
+            replace_section(document, heading, new_content)
+          end
+
+          # Delete a section
+          # @param document [MarkdownDocument] The document to update
+          # @param heading [String] The exact heading text to match
+          # @return [MarkdownDocument] New document without the section
+          def self.delete_section(document, heading)
+            raise ArgumentError, "Document must be a MarkdownDocument" unless document.is_a?(Models::MarkdownDocument)
+
+            # Parse all sections
+            all_sections = Atoms::SectionExtractor.extract_all(document.raw_body)
+
+            # Filter out the target section
+            remaining_sections = all_sections.reject { |s| s[:heading] == heading }
+
+            # Convert to Section models
+            new_sections = remaining_sections.map do |s|
+              Models::Section.new(
+                heading: s[:heading],
+                level: s[:level],
+                content: s[:content] || ""
+              )
+            end
+
+            document.with_sections(new_sections)
+          end
+
+          # Insert a new section before another section
+          # @param document [MarkdownDocument] The document to update
+          # @param before_heading [String] Insert before this heading
+          # @param new_section [Section] The section to insert
+          # @return [MarkdownDocument] New document with inserted section
+          def self.insert_section_before(document, before_heading, new_section)
+            raise ArgumentError, "Document must be a MarkdownDocument" unless document.is_a?(Models::MarkdownDocument)
+            raise ArgumentError, "New section must be a Section" unless new_section.is_a?(Models::Section)
+
+            # Parse all sections
+            all_sections = Atoms::SectionExtractor.extract_all(document.raw_body)
+
+            # Find insertion point
+            insert_index = all_sections.find_index { |s| s[:heading] == before_heading }
+
+            raise SectionNotFoundError, "Section not found: #{before_heading}" unless insert_index
+
+            # Convert existing sections to models
+            sections = all_sections.map do |s|
+              Models::Section.new(
+                heading: s[:heading],
+                level: s[:level],
+                content: s[:content] || ""
+              )
+            end
+
+            # Insert new section
+            sections.insert(insert_index, new_section)
+
+            document.with_sections(sections)
+          end
+
+          # Add a new section at the end
+          # @param document [MarkdownDocument] The document to update
+          # @param new_section [Section] The section to add
+          # @return [MarkdownDocument] New document with added section
+          def self.add_section(document, new_section)
+            raise ArgumentError, "Document must be a MarkdownDocument" unless document.is_a?(Models::MarkdownDocument)
+            raise ArgumentError, "New section must be a Section" unless new_section.is_a?(Models::Section)
+
+            # Parse all sections
+            all_sections = Atoms::SectionExtractor.extract_all(document.raw_body)
+
+            # Convert to models
+            sections = all_sections.map do |s|
+              Models::Section.new(
+                heading: s[:heading],
+                level: s[:level],
+                content: s[:content] || ""
+              )
+            end
+
+            # Add new section
+            sections << new_section
+
+            document.with_sections(sections)
+          end
+        end
+      end
+    end
+  end
+end