ace-support-markdown 0.3.0

data/lib/ace/support/markdown/organisms/document_editor.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Markdown
+      module Organisms
+        # Main API for document editing with fluent interface
+        # Provides safe editing with state management and validation
+        class DocumentEditor
+          attr_reader :document, :file_path, :original_content
+
+          # Create a new DocumentEditor
+          # @param file_path [String] Path to the markdown file
+          def initialize(file_path)
+            raise ArgumentError, "File path cannot be nil" if file_path.nil?
+            raise FileOperationError, "File not found: #{file_path}" unless File.exist?(file_path)
+
+            @file_path = file_path
+            @original_content = File.read(file_path)
+            @document = Models::MarkdownDocument.parse(@original_content, file_path: file_path)
+            @backup_path = nil
+          end
+
+          # Update frontmatter fields
+          # @param updates [Hash] Fields to update
+          # @return [DocumentEditor] self for chaining
+          def update_frontmatter(updates)
+            @document = Molecules::FrontmatterEditor.update(@document, updates)
+            self
+          end
+
+          # Update a single frontmatter field
+          # @param key [String] The field key
+          # @param value [Object] The field value
+          # @return [DocumentEditor] self for chaining
+          def set_field(key, value)
+            @document = Molecules::FrontmatterEditor.update_field(@document, key, value)
+            self
+          end
+
+          # Replace a section's content
+          # @param heading [String] The section heading
+          # @param new_content [String] The new content
+          # @return [DocumentEditor] self for chaining
+          def replace_section(heading, new_content)
+            @document = Molecules::SectionEditor.replace_section(@document, heading, new_content)
+            self
+          end
+
+          # Append to a section
+          # @param heading [String] The section heading
+          # @param content [String] Content to append
+          # @return [DocumentEditor] self for chaining
+          def append_to_section(heading, content)
+            @document = Molecules::SectionEditor.append_to_section(@document, heading, content)
+            self
+          end
+
+          # Delete a section
+          # @param heading [String] The section heading
+          # @return [DocumentEditor] self for chaining
+          def delete_section(heading)
+            @document = Molecules::SectionEditor.delete_section(@document, heading)
+            self
+          end
+
+          # Add a new section
+          # @param heading [String] The section heading
+          # @param content [String] The section content
+          # @param level [Integer] The heading level (default: 2)
+          # @return [DocumentEditor] self for chaining
+          def add_section(heading, content, level: 2)
+            section = Models::Section.new(heading: heading, content: content, level: level)
+            @document = Molecules::SectionEditor.add_section(@document, section)
+            self
+          end
+
+          # Validate the current document state
+          # @param rules [Hash] Optional validation rules
+          # @return [Hash] Result with :valid, :errors, :warnings
+          def validate(rules: {})
+            content = @document.to_markdown
+            Atoms::DocumentValidator.validate(content, rules: rules)
+          end
+
+          # Check if document is valid
+          # @param rules [Hash] Optional validation rules
+          # @return [Boolean]
+          def valid?(rules: {})
+            validate(rules: rules)[:valid]
+          end
+
+          # Save the document to file
+          # @param backup [Boolean] Create backup before writing (default: true)
+          # @param validate_before [Boolean] Validate before writing (default: true)
+          # @param rules [Hash] Optional validation rules
+          # @return [Hash] Result with :success, :backup_path, :errors
+          def save!(backup: true, validate_before: true, rules: {})
+            # Validate before save
+            if validate_before
+              validation = validate(rules: rules)
+              unless validation[:valid]
+                return {
+                  success: false,
+                  backup_path: nil,
+                  errors: validation[:errors]
+                }
+              end
+            end
+
+            # Generate new content
+            new_content = @document.to_markdown
+
+            # Use SafeFileWriter for atomic write with backup
+            result = SafeFileWriter.write(
+              @file_path,
+              new_content,
+              backup: backup
+            )
+
+            if result[:success]
+              @backup_path = result[:backup_path]
+              @original_content = new_content
+            end
+
+            result
+          end
+
+          # Rollback to original content
+          # @return [Hash] Result with :success, :errors
+          def rollback
+            if @backup_path && File.exist?(@backup_path)
+              begin
+                File.write(@file_path, File.read(@backup_path))
+                File.delete(@backup_path)
+                @backup_path = nil
+
+                # Reload document
+                @document = Models::MarkdownDocument.parse(@original_content, file_path: @file_path)
+
+                {success: true, errors: []}
+              rescue => e
+                {success: false, errors: ["Rollback failed: #{e.message}"]}
+              end
+            else
+              {success: false, errors: ["No backup available for rollback"]}
+            end
+          end
+
+          # Get current document content as string
+          # @return [String]
+          def to_markdown
+            @document.to_markdown
+          end
+
+          # Check if document has been modified
+          # @return [Boolean]
+          def modified?
+            @document.to_markdown != @original_content
+          end
+
+          # Get document statistics
+          # @return [Hash]
+          def stats
+            @document.stats
+          end
+
+          # Create a DocumentEditor from content string
+          # @param content [String] The markdown content
+          # @param file_path [String, nil] Optional file path for context
+          # @return [DocumentEditor]
+          def self.from_content(content, file_path: nil)
+            # Create a temporary file if needed
+            if file_path.nil?
+              require "tempfile"
+              temp = Tempfile.new(["markdown", ".md"])
+              temp.write(content)
+              temp.close
+              file_path = temp.path
+            else
+              File.write(file_path, content)
+            end
+
+            new(file_path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/markdown/organisms/safe_file_writer.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+
+module Ace
+  module Support
+    module Markdown
+      module Organisms
+        # Safe file writing with backup and atomic operations
+        # Prevents corruption through temp file + move pattern
+        class SafeFileWriter
+          # Write content to file safely with backup and rollback
+          # @param file_path [String] Target file path
+          # @param content [String] Content to write
+          # @param backup [Boolean] Create backup before writing (default: true)
+          # @param validate [Boolean] Validate content before writing (default: false)
+          # @param validator [Proc, nil] Optional validation proc
+          # @return [Hash] Result with :success, :backup_path, :errors
+          def self.write(file_path, content, backup: true, validate: false, validator: nil)
+            raise ArgumentError, "File path cannot be nil" if file_path.nil?
+            raise ArgumentError, "Content cannot be nil" if content.nil?
+
+            errors = []
+
+            # Validate content if requested
+            if validate || validator
+              validation_errors = perform_validation(content, validator)
+              unless validation_errors.empty?
+                return {
+                  success: false,
+                  backup_path: nil,
+                  errors: validation_errors
+                }
+              end
+            end
+
+            backup_path = nil
+
+            begin
+              # Create backup if requested and file exists
+              if backup && File.exist?(file_path)
+                backup_path = create_backup(file_path)
+              end
+
+              # Write atomically using temp file + move
+              write_atomic(file_path, content)
+
+              {
+                success: true,
+                backup_path: backup_path,
+                errors: []
+              }
+            rescue => e
+              # Rollback from backup if available
+              if backup_path && File.exist?(backup_path)
+                begin
+                  FileUtils.cp(backup_path, file_path)
+                  errors << "Write failed, restored from backup: #{e.message}"
+                rescue => rollback_error
+                  errors << "Write failed and rollback failed: #{e.message} | #{rollback_error.message}"
+                end
+              else
+                errors << "Write failed: #{e.message}"
+              end
+
+              {
+                success: false,
+                backup_path: backup_path,
+                errors: errors
+              }
+            end
+          end
+
+          # Write content with automatic validation
+          # @param file_path [String] Target file path
+          # @param content [String] Content to write
+          # @param rules [Hash] Validation rules
+          # @return [Hash] Result with :success, :backup_path, :errors
+          def self.write_with_validation(file_path, content, rules: {})
+            validator = lambda do |c|
+              result = Atoms::DocumentValidator.validate(c, rules: rules)
+              result[:valid] ? [] : result[:errors]
+            end
+
+            write(file_path, content, backup: true, validate: true, validator: validator)
+          end
+
+          # Create a backup of the file
+          # @param file_path [String] File to backup
+          # @return [String] Backup file path
+          def self.create_backup(file_path)
+            raise FileOperationError, "File not found: #{file_path}" unless File.exist?(file_path)
+
+            timestamp = Time.now.strftime("%Y%m%d_%H%M%S_%L")
+            backup_path = "#{file_path}.backup.#{timestamp}"
+
+            FileUtils.cp(file_path, backup_path)
+            backup_path
+          end
+
+          # Restore from backup
+          # @param file_path [String] Target file path
+          # @param backup_path [String] Backup file path
+          # @return [Hash] Result with :success, :errors
+          def self.restore_from_backup(file_path, backup_path)
+            unless File.exist?(backup_path)
+              return {
+                success: false,
+                errors: ["Backup file not found: #{backup_path}"]
+              }
+            end
+
+            begin
+              FileUtils.cp(backup_path, file_path)
+              {
+                success: true,
+                errors: []
+              }
+            rescue => e
+              {
+                success: false,
+                errors: ["Restore failed: #{e.message}"]
+              }
+            end
+          end
+
+          # Cleanup old backup files
+          # @param file_path [String] Original file path
+          # @param keep [Integer] Number of recent backups to keep (default: 5)
+          # @return [Integer] Number of backups deleted
+          def self.cleanup_backups(file_path, keep: 5)
+            dir = File.dirname(file_path)
+            basename = File.basename(file_path)
+
+            # Find all backup files for this file
+            backup_pattern = File.join(dir, "#{basename}.backup.*")
+            backups = Dir.glob(backup_pattern).sort
+
+            # Keep only the most recent N backups
+            to_delete = backups[0...-keep] || []
+
+            deleted = 0
+            to_delete.each do |backup|
+              File.delete(backup)
+              deleted += 1
+            rescue
+              # Skip files that can't be deleted
+              next
+            end
+
+            deleted
+          end
+
+          private
+
+          # Write file atomically using temp file + move
+          def self.write_atomic(file_path, content)
+            # Get directory and ensure it exists
+            dir = File.dirname(file_path)
+            FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+
+            # Create temp file in same directory (same filesystem for atomic move)
+            temp = Tempfile.new([File.basename(file_path, ".*"), File.extname(file_path)], dir)
+
+            begin
+              # Write content to temp file
+              temp.write(content)
+              temp.close
+
+              # Atomic move (rename) - this is the critical operation
+              # On most filesystems, rename is atomic
+              FileUtils.mv(temp.path, file_path)
+            ensure
+              # Clean up temp file if it still exists
+              temp.close
+              temp.unlink if File.exist?(temp.path)
+            end
+          end
+
+          # Perform validation on content
+          def self.perform_validation(content, validator)
+            errors = []
+
+            # Basic validation - check content can be parsed
+            result = Atoms::FrontmatterExtractor.extract(content)
+            unless result[:valid]
+              errors.concat(result[:errors])
+            end
+
+            # Custom validator
+            if validator.is_a?(Proc)
+              custom_errors = validator.call(content)
+              errors.concat(custom_errors) if custom_errors.is_a?(Array)
+            end
+
+            errors
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/markdown/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Markdown
+      VERSION = "0.3.0"
+    end
+  end
+end

data/lib/ace/support/markdown.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "markdown/version"
+
+# Atoms
+require_relative "markdown/atoms/frontmatter_extractor"
+require_relative "markdown/atoms/frontmatter_serializer"
+require_relative "markdown/atoms/section_extractor"
+require_relative "markdown/atoms/document_validator"
+
+# Molecules
+require_relative "markdown/molecules/frontmatter_editor"
+require_relative "markdown/molecules/section_editor"
+require_relative "markdown/molecules/kramdown_processor"
+require_relative "markdown/molecules/document_builder"
+
+# Organisms
+require_relative "markdown/organisms/document_editor"
+require_relative "markdown/organisms/safe_file_writer"
+
+# Models
+require_relative "markdown/models/markdown_document"
+require_relative "markdown/models/section"
+
+module Ace
+  module Support
+    module Markdown
+      class Error < StandardError; end
+      class ValidationError < Error; end
+      class SectionNotFoundError < Error; end
+      class FileOperationError < Error; end
+    end
+  end
+end

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: ace-support-markdown
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: kramdown-parser-gfm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: ace-support-test-helpers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+description: Provides safe, atomic markdown file operations with frontmatter extraction,
+  section editing, and validation. Prevents file corruption through backup/rollback
+  mechanisms.
+email:
+- mc@cs3b.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/ace/support/markdown.rb
+- lib/ace/support/markdown/atoms/document_validator.rb
+- lib/ace/support/markdown/atoms/frontmatter_extractor.rb
+- lib/ace/support/markdown/atoms/frontmatter_serializer.rb
+- lib/ace/support/markdown/atoms/section_extractor.rb
+- lib/ace/support/markdown/models/markdown_document.rb
+- lib/ace/support/markdown/models/section.rb
+- lib/ace/support/markdown/molecules/document_builder.rb
+- lib/ace/support/markdown/molecules/frontmatter_editor.rb
+- lib/ace/support/markdown/molecules/kramdown_processor.rb
+- lib/ace/support/markdown/molecules/section_editor.rb
+- lib/ace/support/markdown/organisms/document_editor.rb
+- lib/ace/support/markdown/organisms/safe_file_writer.rb
+- lib/ace/support/markdown/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-support-markdown/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-support-markdown/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Safe markdown editing with frontmatter support for ACE gems
+test_files: []