ace-support-markdown 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: caaad5b4c68beae09ec7d4e7d6c09b0b0060cb09eeff550d72473edcb315e87e
+  data.tar.gz: 150a17fa755dbacf16be654f325fcc9eaa520f2e7f69e77150304aeedb8c3e81
+SHA512:
+  metadata.gz: 55dd180392b834db3db26c312f193b68c8ffa2b3ccb9b9099a99ecc365c4b0e3c91153d7329829e88ba323722519727ea62268cc3b9f054beea1d66ce5cced37
+  data.tar.gz: ab08ad8cd7290c10c53021121b247c2eec7db7939bdf2f58356fd7f33690623cbc081b611daf60b8823bc1c03ec1a08e742458f95223671e0f1d3fac855c0aa6

data/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-03-23
+
+### Technical
+- Removed phantom `handbook/**/*` glob from gemspec (no handbook directory exists).
+
+## [0.2.2] - 2026-03-22
+
+### Changed
+- Refreshed README structure with an explicit Purpose section and consistent support-library framing.
+- Updated README testing commands to use `ace-test` instead of `bundle exec` invocations.
+- Added a "Part of ACE" footer link to the package README.
+
+## [0.2.1] - 2026-02-23
+
+### Technical
+- Updated internal dependency version constraints to current releases
+
+## [0.2.0] - 2026-01-03
+
+### Changed
+- **BREAKING**: Minimum Ruby version raised to 3.3.0 (was 3.1.0)
+- Standardized gemspec file patterns with deterministic Dir.glob
+- Added MIT LICENSE file
+
+## [0.1.3] - 2025-11-01
+
+### Changed
+
+- **Dependency Migration**: Updated to use renamed infrastructure gems
+  - Changed dependency from `ace-core` to `ace-support-core`
+  - Part of ecosystem-wide naming convention alignment for infrastructure gems
+
+
+## [0.1.2] - 2025-10-23
+
+### Improved
+
+- **README examples now include educational comments**
+  - Added "why" explanations to all 6 real-world examples
+  - Comments explain reasoning behind patterns (validation, error handling, etc.)
+  - Clarifies ATOM architecture usage and best practices
+  - Explains StandardError rescue patterns and ensure block usage
+
+- **Example 5 refactored to use begin/rescue/ensure pattern**
+  - Replaced multiple rescue blocks with ensure block for rollback
+  - Uses success flag to track operation status
+  - Cleaner, more maintainable error handling pattern
+  - Guarantees cleanup even with non-linear control flow
+
+- **Documentation sync strategy documented**
+  - Added "Maintaining Documentation" section to README
+  - Created comprehensive CONTRIBUTING.md with API sync guidelines
+  - Documents the automated README validation approach
+  - Provides checklist for API changes and documentation updates
+
+### Added
+
+- **Automated README example validation** (`test/integration/readme_examples_test.rb`)
+  - 8 test cases validating all README code examples
+  - Tests run as part of standard test suite
+  - Catches documentation/code mismatches automatically
+  - Ensures examples stay in sync with API evolution
+  - Validates Quick Start, API Documentation, and Real-World Examples
+
+### Fixed
+
+- **Corrected API parameter names in README**
+  - Fixed `validate: true` → `validate_before: true` for DocumentEditor.save!()
+  - Ensures documentation accurately reflects actual API
+  - Caught by new automated README validation tests
+
+## [0.1.1] - 2025-10-23
+
+### Documentation
+
+- **Enhanced README with comprehensive real-world examples** (390+ lines)
+  - Example 1: Task management system (auto-fixing with backup/validation)
+  - Example 2: Documentation updates (bulk operations, nested frontmatter)
+  - Example 3: Complex multi-section operations (complete task workflow)
+  - Example 4: Safe file writing with custom validation
+  - Example 5: Error handling and recovery (rollback, retry logic)
+  - Example 6: Batch operations with progress tracking
+  - All examples based on actual ace-taskflow and ace-docs implementations
+  - Demonstrates error handling patterns, validation rules, and safety features
+
+## [0.1.0] - 2025-10-18
+
+### Added
+- Initial release
+- Frontmatter extraction and serialization atoms
+- Section extraction using Kramdown AST
+- Document validation with hardcoded rules
+- Frontmatter and section editing molecules
+- Safe file writing with backup/rollback
+- Document editor with fluent API
+- Immutable document models
+- Test suite with 100% atom coverage
+
+### Features
+- ATOM architecture (Atoms, Molecules, Organisms, Models)
+- Exact string matching for section identification
+- Atomic file operations with temp file + move pattern
+- Performance: <10ms frontmatter updates, <50ms section edits
+- Zero-corruption design with validation and rollback
+
+[Unreleased]: https://github.com/cs3b/ace/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/cs3b/ace/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/cs3b/ace/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/cs3b/ace/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/cs3b/ace/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/cs3b/ace/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/cs3b/ace/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,221 @@
+# Contributing to ace-support-markdown
+
+Thank you for your interest in contributing to ace-support-markdown! This document provides guidelines for maintaining code quality and documentation accuracy.
+
+## Development Setup
+
+```bash
+git clone https://github.com/your-org/ace-support-markdown.git
+cd ace-support-markdown
+bundle install
+bundle exec rake test
+```
+
+## Code Architecture
+
+This gem follows the **ATOM architecture pattern**:
+
+- **Atoms**: Pure functions with no side effects (`lib/ace/support/markdown/atoms/`)
+- **Molecules**: Composed operations (`lib/ace/support/markdown/molecules/`)
+- **Organisms**: High-level orchestration (`lib/ace/support/markdown/organisms/`)
+- **Models**: Immutable data structures (`lib/ace/support/markdown/models/`)
+
+### Design Principles
+
+1. **Immutability**: Models return new instances on transformation
+2. **Safety First**: All file operations include backup and rollback
+3. **Validation**: Pre-write and post-write validation prevents corruption
+4. **Atomicity**: Operations succeed completely or fail completely
+5. **Clear Errors**: Detailed error messages with actionable information
+
+## Making Changes
+
+### 1. Adding New Features
+
+When adding new functionality:
+
+1. **Identify the layer**: Determine if it's an atom, molecule, organism, or model
+2. **Write tests first**: Add test cases before implementation
+3. **Implement the feature**: Follow existing patterns and conventions
+4. **Update documentation**: Add examples to README.md
+5. **Add README tests**: Create tests in `test/integration/readme_examples_test.rb`
+6. **Run full test suite**: `bundle exec rake test`
+7. **Update CHANGELOG.md**: Document the new feature
+
+### 2. Fixing Bugs
+
+When fixing bugs:
+
+1. **Write a failing test**: Reproduce the bug in a test case
+2. **Fix the implementation**: Resolve the issue
+3. **Verify the fix**: Ensure the test passes
+4. **Check for regressions**: Run full test suite
+5. **Update CHANGELOG.md**: Document the fix
+
+### 3. Updating API
+
+**IMPORTANT**: API changes require updating both code AND documentation.
+
+When modifying the public API:
+
+1. **Update implementation** in `lib/`
+2. **Update corresponding tests** in `test/`
+3. **Update README examples** - this is critical!
+4. **Update README example tests** in `test/integration/readme_examples_test.rb`
+5. **Run test suite** - README tests will catch doc/code mismatches
+6. **Update CHANGELOG.md**
+7. **Consider semver implications**:
+   - Breaking changes → MAJOR version bump
+   - New features → MINOR version bump
+   - Bug fixes → PATCH version bump
+
+### 4. Documentation Sync Strategy
+
+**The Problem**: Documentation can become stale as code evolves.
+
+**Our Solution**: Automated validation of README examples.
+
+The test file `test/integration/readme_examples_test.rb` validates that:
+- Code examples in README.md are syntactically correct
+- Examples work against the current API
+- API behavior matches what's documented
+
+**When you change the API:**
+1. Update the README examples
+2. Update the README example tests
+3. Run `bundle exec rake test`
+4. If tests fail, either:
+   - Fix the README (if docs are wrong)
+   - Fix the test (if test is wrong)
+   - Fix the implementation (if code is wrong)
+
+**This ensures documentation never gets out of sync with reality.**
+
+## Testing Guidelines
+
+### Test Structure
+
+```
+test/
+├── atoms/           # Unit tests for pure functions
+├── molecules/       # Integration tests for operations
+├── organisms/       # End-to-end tests for orchestration
+├── models/          # Tests for data structures
+└── integration/     # Full workflow tests + README validation
+```
+
+### Writing Tests
+
+```ruby
+class MyFeatureTest < Minitest::Test
+  include TestHelpers
+
+  def setup
+    # Setup test environment
+  end
+
+  def teardown
+    # Clean up
+  end
+
+  def test_feature_behavior
+    # Arrange: Set up test data
+    # Act: Execute the feature
+    # Assert: Verify behavior
+  end
+end
+```
+
+### Test Coverage Requirements
+
+- **Atoms**: 100% coverage (pure functions, easy to test)
+- **Molecules**: 95%+ coverage
+- **Organisms**: 95%+ coverage
+- **Integration**: All major workflows covered
+
+Run coverage report:
+```bash
+bundle exec rake test
+# Coverage report in coverage/index.html
+```
+
+## Documentation Guidelines
+
+### README Examples
+
+Examples should be:
+1. **Real-world**: Based on actual use cases from ACE gems
+2. **Complete**: Include setup, execution, and verification
+3. **Commented**: Explain *why*, not just *what*
+4. **Tested**: Have corresponding tests in `readme_examples_test.rb`
+
+### Code Comments
+
+Add comments that explain:
+- **Why** decisions were made (not what the code does)
+- **Edge cases** and special handling
+- **Performance** considerations
+- **Safety** guarantees
+
+Example:
+```ruby
+# Use ensure block for rollback to guarantee cleanup even if control flow is interrupted
+# This handles early returns, raised exceptions, and other non-linear execution paths
+ensure
+  editor.rollback if original_backup && !success_flag
+end
+```
+
+### CHANGELOG Format
+
+Follow [Keep a Changelog](https://keepachangelog.com/) format:
+
+```markdown
+## [0.1.2] - 2025-10-23
+
+### Added
+- New feature description
+
+### Changed
+- Modified behavior description
+
+### Fixed
+- Bug fix description
+```
+
+## Pull Request Process
+
+1. **Create a feature branch**: `git checkout -b feature/my-feature`
+2. **Make your changes**: Follow guidelines above
+3. **Run tests**: `bundle exec rake test`
+4. **Update CHANGELOG.md**: Document your changes
+5. **Commit your changes**: Use clear commit messages
+6. **Push to your fork**: `git push origin feature/my-feature`
+7. **Create Pull Request**: With detailed description
+
+### PR Checklist
+
+- [ ] Tests added/updated and passing
+- [ ] README updated (if API changed)
+- [ ] README example tests updated (if examples changed)
+- [ ] CHANGELOG.md updated
+- [ ] Code follows ATOM architecture
+- [ ] Comments explain *why*, not *what*
+- [ ] No breaking changes (or clearly documented)
+
+## Code Style
+
+Follow Ruby community conventions:
+- 2 spaces for indentation
+- Snake_case for methods and variables
+- CamelCase for classes and modules
+- Descriptive names over short names
+- Limit line length to 120 characters
+
+## Questions?
+
+- Open an issue for bugs or feature requests
+- Start a discussion for questions or ideas
+- Check existing issues and PRs first
+
+Thank you for contributing to ace-support-markdown!

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ACE Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,29 @@
+<div align="center">
+  <h1> ACE - Support Markdown </h1>
+
+  Safe, composable markdown editing tools for ACE libraries and docs.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-support-markdown"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-support-markdown.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+`ace-support-markdown` provides atomic document editing with frontmatter (YAML metadata blocks at the top of markdown files) and section-level updates while preserving document integrity. It is the shared editing layer that packages like [ace-task](../ace-task) and [ace-docs](../ace-docs) depend on for safe, repeatable content mutations.
+
+## Use Cases
+
+**Safely update task and docs content** - use frontmatter and section editing primitives to apply metadata and content changes without risking accidental corruption during automated or agent-driven edits.
+
+**Generate documents programmatically** - build reproducible markdown output with builder-like APIs used by [ace-task](../ace-task) for spec files and [ace-docs](../ace-docs) for generated documentation.
+
+**Preserve history during edits** - maintain backup and rollback safety for write-heavy operations so that tools like [`ace-task`](../ace-task) can update specs confidently in batch workflows.
+
+---
+
+Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+task default: :test

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Markdown
+      module Atoms
+        # Pure function to validate markdown documents and frontmatter
+        # v0.1.0: Uses hardcoded validation rules
+        # v0.2.0: Will support JSON Schema validation (see task 080)
+        class DocumentValidator
+          # Validate complete markdown content (frontmatter + body)
+          # @param content [String] The complete markdown content
+          # @param rules [Hash] Optional validation rules
+          # @return [Hash] Result with :valid (Boolean), :errors (Array), :warnings (Array)
+          def self.validate(content, rules: {})
+            return invalid_result(["Empty content"]) if content.nil? || content.empty?
+
+            errors = []
+            warnings = []
+
+            # Parse frontmatter
+            extractor_result = FrontmatterExtractor.extract(content)
+
+            unless extractor_result[:valid]
+              errors.concat(extractor_result[:errors])
+              return {valid: false, errors: errors, warnings: warnings}
+            end
+
+            # Validate frontmatter structure
+            fm_errors = validate_frontmatter(extractor_result[:frontmatter], rules)
+            errors.concat(fm_errors)
+
+            # Validate body exists
+            if extractor_result[:body].nil? || extractor_result[:body].strip.empty?
+              warnings << "Empty body content"
+            end
+
+            {
+              valid: errors.empty?,
+              errors: errors,
+              warnings: warnings
+            }
+          end
+
+          # Validate only frontmatter hash
+          # @param frontmatter [Hash] The frontmatter data
+          # @param rules [Hash] Optional validation rules
+          # @return [Hash] Result with :valid (Boolean), :errors (Array)
+          def self.validate_frontmatter(frontmatter, rules = {})
+            errors = []
+
+            unless frontmatter.is_a?(Hash)
+              errors << "Frontmatter must be a hash"
+              return errors
+            end
+
+            # Apply required fields validation
+            if rules[:required_fields]
+              rules[:required_fields].each do |field|
+                unless frontmatter.key?(field) || frontmatter.key?(field.to_s)
+                  errors << "Missing required field: #{field}"
+                end
+              end
+            end
+
+            # Apply field type validation
+            if rules[:field_types]
+              rules[:field_types].each do |field, expected_type|
+                value = frontmatter[field] || frontmatter[field.to_s]
+                next unless value
+
+                unless value.is_a?(expected_type)
+                  errors << "Field '#{field}' must be #{expected_type}, got #{value.class}"
+                end
+              end
+            end
+
+            # Apply enum validation
+            if rules[:enums]
+              rules[:enums].each do |field, allowed_values|
+                value = frontmatter[field] || frontmatter[field.to_s]
+                next unless value
+
+                unless allowed_values.include?(value)
+                  errors << "Field '#{field}' must be one of #{allowed_values.join(", ")}, got '#{value}'"
+                end
+              end
+            end
+
+            errors
+          end
+
+          # Validate that content can be round-trip parsed
+          # @param content [String] The markdown content
+          # @return [Boolean] true if content can be safely parsed and rebuilt
+          def self.can_round_trip?(content)
+            return false if content.nil? || content.empty?
+
+            begin
+              # Extract frontmatter
+              result = FrontmatterExtractor.extract(content)
+              return false unless result[:valid]
+
+              # Serialize back
+              serialized = FrontmatterSerializer.serialize(
+                result[:frontmatter],
+                body: result[:body]
+              )
+
+              serialized[:valid]
+            rescue
+              false
+            end
+          end
+
+          private
+
+          def self.invalid_result(errors)
+            {
+              valid: false,
+              errors: errors,
+              warnings: []
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Support
+    module Markdown
+      module Atoms
+        # Pure function to extract YAML frontmatter from markdown content
+        # Separates frontmatter and body content for safe editing
+        class FrontmatterExtractor
+          # Extract frontmatter from markdown content
+          # @param content [String] The markdown content with optional frontmatter
+          # @return [Hash] Result with :frontmatter (Hash), :body (String), :valid (Boolean), :errors (Array)
+          def self.extract(content)
+            return empty_result if content.nil? || content.empty?
+
+            # Check if content starts with YAML frontmatter delimiter
+            unless content.start_with?("---\n")
+              return {
+                frontmatter: {},
+                body: content,
+                valid: false,
+                errors: ["No frontmatter found"]
+              }
+            end
+
+            # Find the ending delimiter (searching from position 4 to skip the opening ---)
+            end_index = content.index("\n---\n", 4)
+
+            unless end_index
+              return {
+                frontmatter: {},
+                body: content[4..-1] || "",
+                valid: false,
+                errors: ["Missing closing '---' delimiter for frontmatter"]
+              }
+            end
+
+            # Extract YAML content (between delimiters) and body content (after delimiters)
+            yaml_content = content[4...end_index]
+            body_content = content[(end_index + 5)..-1] || ""
+
+            # Parse YAML with safe_load
+            begin
+              frontmatter = YAML.safe_load(
+                yaml_content,
+                permitted_classes: [Date, Time, Symbol],
+                permitted_symbols: [],
+                aliases: true
+              ) || {}
+
+              # Ensure frontmatter is a hash
+              unless frontmatter.is_a?(Hash)
+                return {
+                  frontmatter: {},
+                  body: body_content,
+                  valid: false,
+                  errors: ["Frontmatter must be a hash/object, got #{frontmatter.class}"]
+                }
+              end
+
+              {
+                frontmatter: frontmatter,
+                body: body_content,
+                valid: true,
+                errors: []
+              }
+            rescue Psych::SyntaxError => e
+              {
+                frontmatter: {},
+                body: body_content,
+                valid: false,
+                errors: ["YAML syntax error: #{e.message}"]
+              }
+            end
+          end
+
+          # Extract only the frontmatter hash
+          # @param content [String] The markdown content
+          # @return [Hash] The frontmatter data or empty hash
+          def self.frontmatter_only(content)
+            result = extract(content)
+            result[:frontmatter]
+          end
+
+          # Extract only the body content without frontmatter
+          # @param content [String] The markdown content
+          # @return [String] The body content
+          def self.body_only(content)
+            result = extract(content)
+            result[:body]
+          end
+
+          # Check if content has valid frontmatter
+          # @param content [String] The markdown content
+          # @return [Boolean] true if valid frontmatter exists
+          def self.has_frontmatter?(content)
+            result = extract(content)
+            result[:valid]
+          end
+
+          private
+
+          def self.empty_result
+            {
+              frontmatter: {},
+              body: "",
+              valid: false,
+              errors: ["Empty content"]
+            }
+          end
+        end
+      end
+    end
+  end
+end