yaml-janitor 20251113 → 20251115

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 022b412fb7fefdf3b91aae1bb4d47db513c144e1ddb3e99b6d0b83ee9141ac90
-  data.tar.gz: 0d0f1fd010e75a0bceda041960f03432b283091fb8425b2909d3f0f4beaadc80
+  metadata.gz: 9836d954e6602561f6197a639b73183bc96409e93d477191590192d689c669ae
+  data.tar.gz: f1f96ba5f15ec13038060a9ebdf6775a939e46d8b5fddaa190c8664e50925cc8
 SHA512:
-  metadata.gz: 18655c70a33f9db707541e76d6951bbb98b3f227028f933101ff8dd0ea28d2b0fa319a36af467ccb8b52ea7bb46727ef95d8e6625a5b1d647ebdda6ee4601958
-  data.tar.gz: d48f8f842813eb5538c4e939969736b74b1fc8c2414f7be91d9890108d57336015276c6802b35ee138414e88175305c43cf2b85732e9c8ce95873c893083ad1b
+  metadata.gz: 1a02c1e0afd72eb574dff29f779bd9de9a58a4455fee1be3ceb9e598e958608c3302da92784a1730f08927ef0f1a221f52a72b556d2d8d7e4de970252f9bfbe7
+  data.tar.gz: bded6694abd1eb893bcde70ac3144315ececc62a92eb20f7730ec85075b2bb14dd3ad696a32dd431644cb7f0b2fb559dad9e53a21094629352013bc296f029ea

data/README.md

@@ -1,13 +1,13 @@
 # yaml-janitor
 
-A YAML linter built on psych-pure that preserves comments while detecting and
-fixing issues.
+A YAML linter and formatter built on psych-pure that preserves comments while
+formatting files.
 
 ## Why?
 
 Traditional YAML tools destroy comments when editing files. yaml-janitor uses
-psych-pure's comment-preserving parser to lint and fix YAML files without
-losing valuable documentation.
+psych-pure's comment-preserving parser to format YAML files without losing
+valuable documentation.
 
 ## Installation
 
@@ -25,7 +25,7 @@ gem 'yaml-janitor'
 
 ### CLI
 
-Check a single file:
+Check a single file (reports formatting issues):
 ```bash
 yaml-janitor config.yml
 ```
@@ -35,14 +35,19 @@ Check all YAML files in a directory:
 yaml-janitor containers/
 ```
 
-Auto-fix issues:
+Format files in-place:
 ```bash
 yaml-janitor --fix config.yml
 ```
 
-Run specific rules:
+Format with custom indentation:
 ```bash
-yaml-janitor --rules multiline_certificate config.yml
+yaml-janitor --fix --indentation 4 config.yml
+```
+
+Show diff of formatting changes:
+```bash
+yaml-janitor --diff config.yml
 ```
 
 ### Ruby API
@@ -50,21 +55,27 @@ yaml-janitor --rules multiline_certificate config.yml
 ```ruby
 require 'yaml_janitor'
 
-# Lint a file
+# Check a file for formatting issues
 result = YamlJanitor.lint_file("config.yml")
 result[:violations].each do |violation|
-  puts violation
+  puts "#{violation.file}: #{violation.message}"
 end
 
-# Lint and fix
-result = YamlJanitor.lint_file("config.yml", fix: true)
+# Format a file in-place
+result = YamlJanitor.format_file("config.yml")
 if result[:fixed]
-  puts "Fixed! New content:\n#{result[:output]}"
+  puts "Formatted!"
 end
 
-# Lint a string
+# Format a string
 yaml_string = File.read("config.yml")
-result = YamlJanitor.lint(yaml_string)
+result = YamlJanitor.format(yaml_string)
+puts result[:output]
+
+# Use custom config
+config = YamlJanitor::Config.new(overrides: { indentation: 4 })
+linter = YamlJanitor::Linter.new(config: config)
+result = linter.lint_file("config.yml", fix: true)
 ```
 
 ## Configuration
@@ -72,29 +83,15 @@ result = YamlJanitor.lint(yaml_string)
 Create a `.yaml-janitor.yml` file in your project root:
 
 ```yaml
-# Formatting options (applied during --fix)
+# Formatting options
 indentation: 2
 line_width: 80
-sequence_indent: false
-
-# Rule configuration
-rules:
-  multiline_certificate:
-    enabled: true
-  consistent_indentation:
-    enabled: true
 ```
 
 ### Configuration Options
 
-**Formatting**:
 - `indentation`: Number of spaces for indentation (default: 2)
-- `line_width`: Maximum line width before wrapping (default: 80)
-- `sequence_indent`: Indent sequences under their key (default: false)
-
-**Rules**:
-- `multiline_certificate`: Detects multi-line certificates in double-quoted strings
-- `consistent_indentation`: Detects and fixes inconsistent indentation
+- `line_width`: Maximum line width before wrapping (default: 80, not yet implemented)
 
 ### Command Line Overrides
 
@@ -106,47 +103,43 @@ yaml-janitor --indentation 4 --line-width 100 config.yml
 yaml-janitor --config production.yml containers/
 ```
 
-## Rules
+## How It Works
 
-### multiline_certificate
+yaml-janitor uses a two-phase approach:
 
-Detects multi-line certificates embedded in double-quoted strings. This pattern
-triggers a psych-pure parser bug.
+1. **Parse**: Load YAML with psych-pure, preserving comment metadata
+2. **Format**: Emit YAML using custom formatter with full control over style
 
-```yaml
-# BAD (will trigger violation)
-DISCOURSE_SAML_CERT: "-----BEGIN CERTIFICATE-----
-MIIDGDCCAgCgAwIBAgIVAMP/9hm9Vl3/23QoXrL8hQ31DLwRMA0GCSqGSIb3DQEB
------END CERTIFICATE-----"
-
-# GOOD (use block literal style)
-DISCOURSE_SAML_CERT: |
-  -----BEGIN CERTIFICATE-----
-  MIIDGDCCAgCgAwIBAgIVAMP/9hm9Vl3/23QoXrL8hQ31DLwRMA0GCSqGSIb3DQEB
-  -----END CERTIFICATE-----
-```
+When you run `yaml-janitor --fix`, it:
+- Loads your YAML file with comments preserved
+- Formats it according to configuration (indentation, line width, etc.)
+- Verifies semantics are unchanged (paranoid mode)
+- Writes the formatted output back to the file
 
-**Auto-fix**: Not yet implemented (requires psych-pure enhancements)
+### Formatting Rules
 
-### consistent_indentation
+The formatter enforces:
+- **Consistent indentation** (default: 2 spaces)
+- **Block style for arrays and mappings** (never flow style like `[a, b, c]`)
+- **Normalized string quoting** (only quotes when necessary)
+- **Proper line breaks** between top-level keys
 
-Detects inconsistent indentation (mixing 2-space, 4-space, etc.) in YAML files.
+### Comment Preservation
 
-```yaml
-# BAD (inconsistent: 4 and 8 spaces)
-database:
-    host: "localhost"
-config:
-        timeout: 30
-
-# GOOD (consistent: 2 spaces)
-database:
-  host: "localhost"
-config:
-  timeout: 30
-```
+Comments are preserved in most locations:
+- Leading comments (before keys)
+- Trailing comments (after values)
+- Mid-document comments (between keys)
+
+Known limitation: Inline comments on mapping keys (e.g., `servers: # comment`)
+may be repositioned as leading comments on the next key due to psych-pure's
+comment tracking.
+
+### Safety
 
-**Auto-fix**: Yes, normalizes to configured indentation (default: 2 spaces)
+All formatting changes are verified with paranoid mode: the original YAML and
+formatted YAML are both parsed and compared for semantic equality. If they
+differ, the tool errors out instead of writing the file.
 
 ## Development
 
@@ -164,12 +157,12 @@ bundle exec rake test
 ### Test Coverage
 
 Integration tests verify:
-- Comment preservation during fixes
+- Comment preservation during formatting
 - Indentation normalization
 - Paranoid mode (semantic verification)
-- Config loading and rule enable/disable
-- Multi-line certificate detection
-- Clean files pass without violations
+- Config loading and overrides
+- Parse error detection
+- Idempotent formatting (clean files pass without violations)
 
 ## Background
 

data/bin/yaml-janitor

@@ -7,27 +7,34 @@ def print_usage
   puts <<~USAGE
     Usage: yaml-janitor [options] <file_or_directory>
 
+    yaml-janitor is a YAML linter and formatter that preserves comments.
+
     Options:
-      --fix               Auto-fix issues where possible
-      --rules RULES       Comma-separated list of rules (default: all)
+      --fix               Format files in-place (without this, just check)
+      --diff              Show diff of formatting changes
       --config PATH       Path to config file (default: .yaml-janitor.yml)
       --indentation N     Number of spaces for indentation (default: 2)
       --line-width N      Maximum line width (default: 80)
       --help              Show this help message
 
     Examples:
+      # Check files (report issues)
       yaml-janitor config.yml
+      yaml-janitor containers/
+
+      # Format files in-place
       yaml-janitor --fix config.yml
-      yaml-janitor --rules multiline_certificate containers/
-      yaml-janitor --config my-config.yml --fix config.yml
-      yaml-janitor --indentation 4 --line-width 100 config.yml
+      yaml-janitor --fix --indentation 4 containers/
+
+      # Show diff of formatting changes
+      yaml-janitor --diff config.yml
   USAGE
   exit 0
 end
 
 # Parse args
 fix = false
-rules = :all
+diff = false
 config_path = nil
 config_overrides = {}
 paths = []
@@ -37,9 +44,8 @@ while i < ARGV.length
   case ARGV[i]
   when "--fix"
     fix = true
-  when "--rules"
-    i += 1
-    rules = ARGV[i].split(",").map(&:to_sym)
+  when "--diff"
+    diff = true
   when "--config"
     i += 1
     config_path = ARGV[i]
@@ -69,10 +75,11 @@ end
 
 # Process files
 config = YamlJanitor::Config.new(config_path: config_path, overrides: config_overrides)
-linter = YamlJanitor::Linter.new(rules: rules, config: config)
+linter = YamlJanitor::Linter.new(config: config)
 total_files = 0
-total_violations = 0
 files_with_violations = []
+formatted_files = []
+failed_files = []
 
 paths.each do |path|
   if File.directory?(path)
@@ -82,18 +89,23 @@ paths.each do |path|
       total_files += 1
       result = linter.lint_file(file, fix: fix)
 
-      if result[:violations].any?
+      if result[:error]
+        failed_files << { file: file, error: result[:error] }
+        puts "✗ #{file}: #{result[:error].message}"
+      elsif result[:violations].any?
         files_with_violations << file
-        total_violations += result[:violations].length
-
-        puts "\n#{file}:"
-        result[:violations].each do |violation|
-          puts "  #{violation}"
-        end
-
-        if fix && result[:fixed]
-          puts "  ✓ Fixed"
+        if fix
+          formatted_files << file
+          puts "✓ #{file} (formatted)"
+        elsif diff
+          puts "✗ #{file}: needs formatting"
+          puts linter.generate_diff(result[:original], result[:formatted], file)
+          puts ""
+        else
+          puts "✗ #{file}: needs formatting"
         end
+      elsif !fix && !diff
+        puts "✓ #{file}"
       end
     end
   elsif File.file?(path)
@@ -101,18 +113,23 @@ paths.each do |path|
     total_files += 1
     result = linter.lint_file(path, fix: fix)
 
-    if result[:violations].any?
+    if result[:error]
+      failed_files << { file: path, error: result[:error] }
+      puts "✗ #{path}: #{result[:error].message}"
+    elsif result[:violations].any?
       files_with_violations << path
-      total_violations += result[:violations].length
-
-      puts "\n#{path}:"
-      result[:violations].each do |violation|
-        puts "  #{violation}"
-      end
-
-      if fix && result[:fixed]
-        puts "  ✓ Fixed"
+      if fix
+        formatted_files << path
+        puts "✓ #{path} (formatted)"
+      elsif diff
+        puts "✗ #{path}: needs formatting"
+        puts linter.generate_diff(result[:original], result[:formatted], path)
+        puts ""
+      else
+        puts "✗ #{path}: needs formatting"
       end
+    elsif !fix && !diff
+      puts "✓ #{path}"
     end
   else
     puts "Warning: #{path} not found"
@@ -121,10 +138,21 @@ end
 
 # Summary
 puts "\n" + "="*60
-puts "Checked #{total_files} files"
-puts "Found #{total_violations} violations in #{files_with_violations.length} files"
+if fix
+  puts "Formatted #{formatted_files.length}/#{total_files} files"
+else
+  puts "Checked #{total_files} files"
+  puts "#{files_with_violations.length} files need formatting"
+end
 
-if total_violations > 0
+if failed_files.any?
+  puts "\nFailed files:"
+  failed_files.each do |failure|
+    puts "  #{failure[:file]}: #{failure[:error].message}"
+  end
+  exit 1
+elsif files_with_violations.any? && !fix
+  puts "\nRun with --fix to format these files"
   exit 1
 else
   puts "✓ All files clean!"

data/lib/yaml_janitor/config.rb

@@ -7,7 +7,6 @@ module YamlJanitor
     DEFAULT_CONFIG = {
       indentation: 2,
       line_width: 80,
-      sequence_indent: false,
       rules: {
         multiline_certificate: { enabled: true },
         consistent_indentation: { enabled: true }
@@ -30,10 +29,6 @@ module YamlJanitor
       @config[:line_width]
     end
 
-    def sequence_indent
-      @config[:sequence_indent]
-    end
-
     def rule_enabled?(rule_name)
       rule_config = @config[:rules][rule_name.to_sym]
       rule_config && rule_config[:enabled] != false
@@ -46,8 +41,7 @@ module YamlJanitor
     def dump_options
       {
         indentation: indentation,
-        line_width: line_width,
-        sequence_indent: sequence_indent
+        line_width: line_width
       }
     end
 

data/lib/yaml_janitor/emitter.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module YamlJanitor
+  # Emitter takes a loaded YAML document (with comments) and formats it
+  # according to configuration rules. Unlike Psych::Pure.dump, we have
+  # complete control over formatting choices.
+  class Emitter
+    def initialize(node, config)
+      @node = node
+      @config = config
+      @output = []
+    end
+
+    def emit
+      # Emit any leading comments on the root document
+      emit_comments(get_comments(@node, :leading), 0)
+
+      emit_document(@node)
+      @output.join("\n") + "\n"
+    end
+
+    private
+
+    def emit_document(node, indent: 0)
+      case node
+      when Psych::Pure::LoadedHash
+        emit_mapping(node, indent)
+      when Hash
+        emit_mapping(node, indent)
+      when Psych::Pure::LoadedObject
+        # Check if it wraps an array
+        inner = node.__getobj__
+        if inner.is_a?(Array)
+          emit_sequence(inner, indent, loaded_object: node)
+        else
+          emit_node(inner, indent)
+        end
+      when Array
+        emit_sequence(node, indent)
+      else
+        emit_scalar(node, indent)
+      end
+    end
+
+    def emit_mapping(hash, indent)
+      # Use psych_keys if available (LoadedHash), otherwise fall back to regular iteration
+      entries = if hash.respond_to?(:psych_keys)
+        hash.psych_keys.map { |pk| [pk.key_node, pk.value_node] }
+      else
+        hash.to_a
+      end
+
+      entries.each_with_index do |(key, value), index|
+        # Add blank line between top-level keys if configured
+        actual_value = value.is_a?(Psych::Pure::LoadedObject) ? value.__getobj__ : value
+        @output << "" if index > 0 && indent == 0 && should_add_blank_line?(actual_value)
+
+        # Emit any leading comments
+        emit_comments(get_comments(key, :leading), indent)
+
+        # Emit the key-value pair
+        key_str = scalar_to_string(key.is_a?(Psych::Pure::LoadedObject) ? key.__getobj__ : key)
+
+        # Unwrap LoadedObject to check the actual type
+        actual_value = value.is_a?(Psych::Pure::LoadedObject) ? value.__getobj__ : value
+
+        case actual_value
+        when Hash, Psych::Pure::LoadedHash, Array
+          # Complex value - put on next line
+          line = "#{' ' * indent}#{key_str}:"
+
+          # Check for inline comment on the value
+          if (trailing = get_comments(value, :trailing))
+            inline = trailing.find { |c| c.inline? }
+            if inline
+              line += "  #{inline.value}"
+              trailing = trailing.reject { |c| c.inline? }
+            end
+          end
+
+          @output << line
+          emit_node(value, indent + indentation)
+
+          # Emit any non-inline trailing comments
+          emit_comments(trailing, indent) if trailing&.any?
+        else
+          # Simple value - same line
+          value_str = scalar_to_string(actual_value)
+          line = "#{' ' * indent}#{key_str}: #{value_str}"
+
+          # Check for inline comment on the value
+          if (trailing = get_comments(value, :trailing))
+            inline = trailing.find { |c| c.inline? }
+            line += "  #{inline.value}" if inline
+          end
+
+          @output << line
+        end
+
+        # Emit any trailing comments on the key itself
+        emit_comments(get_comments(key, :trailing), indent)
+      end
+    end
+
+    def emit_sequence(array, indent, loaded_object: nil)
+      array.each_with_index do |item, index|
+        # Emit any leading comments (check both the item and the LoadedObject wrapper)
+        comments = get_comments(item, :leading) || (loaded_object ? get_comments(loaded_object, :leading) : nil)
+        emit_comments(comments, indent)
+
+        case item
+        when Hash, Psych::Pure::LoadedHash
+          # Complex item - use compact style (dash on same line as first key)
+          emit_compact_hash_item(item, indent)
+        when Array
+          # Nested array
+          @output << "#{' ' * indent}-"
+          emit_node(item, indent + indentation)
+        else
+          # Simple item - same line
+          item_str = scalar_to_string(item)
+          @output << "#{' ' * indent}- #{item_str}"
+        end
+
+        # Emit any trailing comments
+        emit_comments(get_comments(item, :trailing), indent)
+      end
+    end
+
+    def emit_compact_hash_item(hash, indent)
+      # Emit hash as array item in compact style:
+      # - key1: value1
+      #   key2: value2
+
+      # Use psych_keys if available (LoadedHash), otherwise fall back to regular iteration
+      entries = if hash.respond_to?(:psych_keys)
+        hash.psych_keys.map { |pk| [pk.key_node, pk.value_node] }
+      else
+        hash.to_a
+      end
+
+      entries.each_with_index do |(key, value), index|
+        # Emit any leading comments
+        emit_comments(get_comments(key, :leading), indent + (index > 0 ? indentation : 0))
+
+        # Get the actual key and value (unwrap LoadedObject)
+        key_str = scalar_to_string(key.is_a?(Psych::Pure::LoadedObject) ? key.__getobj__ : key)
+        actual_value = value.is_a?(Psych::Pure::LoadedObject) ? value.__getobj__ : value
+
+        # First item gets the dash, rest are indented
+        prefix = index == 0 ? "#{' ' * indent}- " : "#{' ' * (indent + indentation)}"
+
+        case actual_value
+        when Hash, Psych::Pure::LoadedHash, Array
+          # Complex value - put on next line
+          line = "#{prefix}#{key_str}:"
+
+          # Check for inline comment on the value
+          if (trailing = get_comments(value, :trailing))
+            inline = trailing.find { |c| c.inline? }
+            if inline
+              line += "  #{inline.value}"
+              trailing = trailing.reject { |c| c.inline? }
+            end
+          end
+
+          @output << line
+          emit_node(value, indent + indentation * 2)
+
+          # Emit any non-inline trailing comments
+          emit_comments(trailing, indent + indentation) if trailing&.any?
+        else
+          # Simple value - same line
+          value_str = scalar_to_string(actual_value)
+          line = "#{prefix}#{key_str}: #{value_str}"
+
+          # Check for inline comment on the value
+          if (trailing = get_comments(value, :trailing))
+            inline = trailing.find { |c| c.inline? }
+            line += "  #{inline.value}" if inline
+          end
+
+          @output << line
+        end
+
+        # Emit any trailing comments on the key itself
+        emit_comments(get_comments(key, :trailing), indent + (index > 0 ? indentation : 0))
+      end
+    end
+
+    def emit_node(node, indent)
+      case node
+      when Psych::Pure::LoadedHash, Hash
+        emit_mapping(node, indent)
+      when Psych::Pure::LoadedObject
+        emit_node(node.__getobj__, indent)
+      when Array
+        emit_sequence(node, indent)
+      else
+        @output << "#{' ' * indent}#{scalar_to_string(node)}"
+      end
+    end
+
+    def emit_scalar(value, indent)
+      @output << "#{' ' * indent}#{scalar_to_string(value)}"
+    end
+
+    def scalar_to_string(value)
+      case value
+      when String
+        format_string(value)
+      when Symbol
+        ":#{value}"
+      when NilClass
+        "null"
+      when TrueClass, FalseClass
+        value.to_s
+      when Numeric
+        value.to_s
+      else
+        value.to_s
+      end
+    end
+
+    def format_string(str)
+      # Choose appropriate string style
+      if str.include?("\n")
+        # Multi-line string - use literal block scalar
+        format_literal_string(str)
+      elsif needs_quoting?(str)
+        # Quote if necessary
+        if str.include?('"') && !str.include?("'")
+          "'#{str.gsub("'", "''")}'"
+        else
+          "\"#{str.gsub('"', '\\"')}\""
+        end
+      else
+        str
+      end
+    end
+
+    def format_literal_string(str)
+      # For now, just quote it - we can enhance this later
+      "\"#{str.gsub('"', '\\"').gsub("\n", '\\n')}\""
+    end
+
+    def needs_quoting?(str)
+      # Basic rules - quote if:
+      # - Starts/ends with whitespace
+      # - Contains : or # or special chars
+      # - Looks like a boolean/null/number
+      return true if str.match?(/\A\s|\s\z/)
+      return true if str.match?(/[:#\[\]{}]/)
+      return true if str.match?(/\A(true|false|null|~|yes|no|on|off)\z/i)
+      return true if str.match?(/\A[-+]?[0-9]/)
+      false
+    end
+
+    def emit_comments(comments, indent)
+      return unless comments&.any?
+
+      comments.each do |comment|
+        @output << "#{' ' * indent}#{comment.value}"
+      end
+    end
+
+    def get_comments(node, type)
+      return nil unless node.respond_to?(:psych_node)
+      return nil unless node.psych_node.respond_to?(:comments?)
+      return nil unless node.psych_node.comments?
+
+      case type
+      when :leading
+        node.psych_node.comments.leading
+      when :trailing
+        node.psych_node.comments.trailing
+      end
+    end
+
+    def should_add_blank_line?(value)
+      # Add blank line before complex structures
+      value.is_a?(Hash) || value.is_a?(Array)
+    end
+
+    def indentation
+      @config.indentation
+    end
+  end
+end

data/lib/yaml_janitor/linter.rb

@@ -2,11 +2,8 @@
 
 module YamlJanitor
   class Linter
-    attr_reader :rules
-
-    def initialize(rules: :all, config: nil, config_path: nil)
+    def initialize(config: nil, config_path: nil)
       @config = config || Config.new(config_path: config_path)
-      @rules = load_rules(rules)
     end
 
     # Lint a file, optionally fixing issues
@@ -28,22 +25,24 @@ module YamlJanitor
       # Load with comments
       loaded = Psych::Pure.load(yaml_content, comments: true)
 
-      # Check for violations
-      @rules.each do |rule|
-        violations += rule.check(loaded, file: file)
+      # Format using our custom emitter
+      formatted = Emitter.new(loaded, @config).emit
+
+      # Check if formatting would change the file
+      if yaml_content != formatted
+        violations << Violation.new(
+          rule: :formatting,
+          message: "File needs formatting (indentation, style, or whitespace issues)",
+          file: file
+        )
       end
 
       # Apply fixes if requested
       output = yaml_content
       fixed = false
 
-      if fix && violations.any?
-        @rules.each do |rule|
-          rule.fix!(loaded)
-        end
-
-        # Dump back to YAML with configured options
-        output = Psych::Pure.dump(loaded, **@config.dump_options)
+      if fix
+        output = formatted
         fixed = true
 
         # Paranoid mode: verify semantics match
@@ -53,7 +52,9 @@ module YamlJanitor
       {
         violations: violations,
         fixed: fixed,
-        output: output
+        output: output,
+        original: yaml_content,
+        formatted: formatted
       }
     rescue => e
       {
@@ -68,34 +69,47 @@ module YamlJanitor
       }
     end
 
-    private
-
-    def load_rules(rule_specs)
-      available_rules = {
-        multiline_certificate: Rules::MultilineCertificate,
-        consistent_indentation: Rules::ConsistentIndentation
-      }
-
-      if rule_specs == :all
-        # Load all enabled rules from config
-        rule_names = available_rules.keys.select do |name|
-          @config.rule_enabled?(name)
+    # Generate unified diff between original and formatted content
+    def generate_diff(original, formatted, path)
+      require 'tempfile'
+
+      # Write to temp files and use system diff
+      Tempfile.create(['original', '.yml']) do |orig_file|
+        Tempfile.create(['formatted', '.yml']) do |fmt_file|
+          orig_file.write(original)
+          orig_file.flush
+          fmt_file.write(formatted)
+          fmt_file.flush
+
+          # Use git diff if available (better formatting), fall back to diff
+          diff_cmd = if system('which git > /dev/null 2>&1')
+            "git diff --no-index --color=always #{orig_file.path} #{fmt_file.path}"
+          else
+            "diff -u #{orig_file.path} #{fmt_file.path}"
+          end
+
+          diff_output = `#{diff_cmd}`
+
+          # Replace temp file paths with actual path
+          # Git adds a/ and b/ prefixes (or just a/b for temp files)
+          orig_path_pattern = Regexp.escape(orig_file.path)
+          fmt_path_pattern = Regexp.escape(fmt_file.path)
+
+          # Handle various git diff formats
+          diff_output.gsub(/a\/#{orig_path_pattern}/, path)
+                    .gsub(/b\/#{fmt_path_pattern}/, "#{path} (formatted)")
+                    .gsub(/a#{orig_path_pattern}/, path)
+                    .gsub(/b#{fmt_path_pattern}/, "#{path} (formatted)")
+                    .gsub(/#{orig_path_pattern}/, path)
+                    .gsub(/#{fmt_path_pattern}/, "#{path} (formatted)")
         end
-      elsif rule_specs.is_a?(Array)
-        rule_names = rule_specs
-      else
-        raise Error, "Invalid rules specification: #{rule_specs.inspect}"
       end
-
-      rule_names.map do |name|
-        rule_class = available_rules[name.to_sym]
-        raise Error, "Unknown rule: #{name}" unless rule_class
-        next unless @config.rule_enabled?(name)
-
-        rule_class.new(@config.rule_config(name))
-      end.compact
+    rescue => e
+      "Error generating diff: #{e.message}"
     end
 
+    private
+
     def verify_semantics!(original, fixed)
       original_data = YAML.load(original)
       fixed_data = YAML.load(fixed)

data/lib/yaml_janitor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module YamlJanitor
-  VERSION = "20251113"
+  VERSION = "20251115"
 end

data/lib/yaml_janitor.rb

@@ -5,11 +5,9 @@ require "yaml"
 
 require_relative "yaml_janitor/version"
 require_relative "yaml_janitor/config"
+require_relative "yaml_janitor/emitter"
 require_relative "yaml_janitor/linter"
-require_relative "yaml_janitor/rule"
 require_relative "yaml_janitor/violation"
-require_relative "yaml_janitor/rules/multiline_certificate"
-require_relative "yaml_janitor/rules/consistent_indentation"
 
 module YamlJanitor
   class Error < StandardError; end
@@ -17,16 +15,16 @@ module YamlJanitor
   class SemanticMismatchError < Error; end
 
   class << self
-    # Convenience method to lint a file
-    def lint_file(path, rules: :all, fix: false)
-      linter = Linter.new(rules: rules)
-      linter.lint_file(path, fix: fix)
+    # Convenience method to format a file
+    def format_file(path, config: nil)
+      linter = Linter.new(config: config)
+      linter.lint_file(path, fix: true)
     end
 
-    # Convenience method to lint a string
-    def lint(yaml_string, rules: :all, fix: false)
-      linter = Linter.new(rules: rules)
-      linter.lint(yaml_string, fix: fix)
+    # Convenience method to format a string
+    def format(yaml_string, config: nil)
+      linter = Linter.new(config: config)
+      linter.lint(yaml_string, fix: true)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yaml-janitor
 version: !ruby/object:Gem::Version
-  version: '20251113'
+  version: '20251115'
 platform: ruby
 authors:
 - ducks
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-13 00:00:00.000000000 Z
+date: 2025-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: psych-pure
@@ -66,6 +66,7 @@ files:
 - bin/yaml-janitor
 - lib/yaml_janitor.rb
 - lib/yaml_janitor/config.rb
+- lib/yaml_janitor/emitter.rb
 - lib/yaml_janitor/linter.rb
 - lib/yaml_janitor/rule.rb
 - lib/yaml_janitor/rules/consistent_indentation.rb