yamlfmt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 571a8a62760ac20bcdba1b1d26ff3b269bf4714dedb060d764e6b0dfacecf47f
+  data.tar.gz: 6d41e7d35bb249788d291d407ab2569201fc0cd96f6d5fa48fed84f7394a089d
+SHA512:
+  metadata.gz: eda1c531fd15373645247284edcc73c62c0568c31a635bc91277a05797e2f137bbdbabd4a473ac98be85967a732937c42c29060c1e33c5dad87be1ab7adcb4e7
+  data.tar.gz: 7a2f78db1ceee85098fea0ca4bdb4e71877c89c5aaacfda43a58510282a5ffdd2c2c03b157dbd8c4ce6c012616cd500bcde0eabfa51bf22a3334fda1110f02c5

data/.ruby-version

@@ -0,0 +1 @@
+3.3.5

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryuki
+
+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,207 @@
+# yamlfmt
+
+`yamlfmt` is a comment-preserving, minimal-diff YAML formatter for Ruby. It
+applies targeted edits to the original source instead of re-emitting the entire
+document, preserving comments and untouched formatting.
+
+It is built on [psych-pure](https://github.com/kddnewton/psych-pure).
+
+This project is unrelated to the Go formatter with the same name.
+
+## Installation
+
+Install yamlfmt from RubyGems:
+
+```console
+$ gem install yamlfmt
+```
+
+To use it in a Rails application, add it to the application's `Gemfile`:
+
+```ruby
+group :development, :test do
+  gem "yamlfmt", require: false
+end
+```
+
+Then run `bundle install` and invoke it with `bundle exec yamlfmt`.
+
+yamlfmt requires Ruby 3.3 or newer.
+
+## Usage
+
+Running without an option checks YAML files below the current directory. It
+reports formatting issues but never modifies a file.
+
+```console
+$ yamlfmt
+$ yamlfmt config/locales
+$ yamlfmt config/application.yml
+```
+
+Directories are searched recursively for `.yml` and `.yaml` files. A file
+passed directly is checked regardless of its extension. Hidden directories,
+including `.github`, are searched; `.git` and symbolic links are always
+skipped.
+
+Preview a unified diff before applying changes:
+
+```console
+$ yamlfmt --diff
+$ yamlfmt --fix
+```
+
+`--fix` with no path rewrites every applicable YAML file below the current
+directory. Running `--diff` first is strongly recommended. `--fix` and
+`--diff` cannot be combined.
+
+Create a starter configuration:
+
+```console
+$ yamlfmt --init
+```
+
+Other options are available through `yamlfmt --help`. Colors are used only when
+writing a diff to a terminal and can be disabled with `--no-color`.
+
+Check mode ends with the number of files inspected, issues found, and issues
+that can be corrected automatically:
+
+```text
+12 files inspected, 5 issues found, 4 autocorrectable
+```
+
+Fix mode instead reports how many issues and files were actually corrected,
+followed by the number of issues that remain when applicable:
+
+```text
+12 files inspected, 5 issues found, 4 corrected in 2 files, 1 issue remains
+```
+
+Warnings and failed files are reported separately from issue counts. Diff mode
+does not print a summary, so its output can be redirected or piped as a patch.
+
+### Exit status
+
+| Status | Meaning |
+|---|---|
+| 0 | No issues, no targets, or all requested fixes succeeded |
+| 1 | Formatting issues in check/diff mode, invalid input, an unsupported file, or a failed fix |
+
+When one file fails, yamlfmt continues processing the remaining files. In fix
+mode, files that pass validation are still rewritten, and the final status is
+1 if any file failed.
+
+## Configuration
+
+yamlfmt reads `.yamlfmt.yml` from the current directory only. It does not search
+parent directories.
+
+```yaml
+rules:
+  trailing-whitespace: true
+  final-newline: true
+  blank-lines:
+    max: 1
+  unnecessary-quotes: true
+
+exclude:
+  - vendor
+  - node_modules
+  - "*.generated.yml"
+  - "tmp/**"
+```
+
+Set a rule to `false` to disable it. A mapping overrides that rule's options.
+Unknown rule and option names produce warnings; invalid values are errors.
+
+Exclude patterns are relative to the current directory:
+
+- A name without `/`, such as `node_modules`, matches a file or directory with
+  that name at any depth. Matching a directory excludes everything below it.
+- A path such as `config/generated` matches that path and everything below it.
+- `*` matches characters within one path component, `?` matches one character,
+  and a final `/**` matches everything below a directory.
+- Gitignore-style negation with `!` is not supported.
+
+Quote patterns beginning with `*` in YAML so they are not interpreted as YAML
+aliases. Exclusions also apply to files passed explicitly.
+
+yamlfmt does not read `.gitignore`. Configure exclusions in `.yamlfmt.yml`.
+
+## Rules
+
+### `trailing-whitespace`
+
+Removes spaces and tabs at line endings.
+
+### `final-newline`
+
+Adds a missing final newline and removes extra blank lines at the end of a
+file. Existing LF or CRLF line endings are preserved.
+
+### `blank-lines`
+
+Limits consecutive blank lines within a file. Whitespace-only lines count as
+blank. The default maximum is one.
+
+### `unnecessary-quotes`
+
+Removes single or double quotes only when Psych would emit the string in plain
+style. Values such as `yes`, numbers, dates, `null`, interpolation placeholders,
+and strings with YAML indicators remain quoted. Both YAML values and keys are
+checked.
+
+For example, only the safely unquotable value is changed:
+
+```diff
+-foo: "hello"
++foo: hello
+ bar: "yes"
+ date: "2026-09-06"
+```
+
+## Safety and known limitations
+
+Before a changed file is written, yamlfmt checks that:
+
+- `Psych.safe_load_stream` produces an equivalent Ruby value;
+- the number and logical content of comments are unchanged; and
+- the corrected source can still be parsed as supported YAML.
+
+The file is not written if validation fails.
+
+yamlfmt skips line-based rules for an entire file when it contains a block
+scalar (`|` or `>`). `unnecessary-quotes` still runs. This restriction avoids a
+known psych-pure location bug; yamlfmt prints a warning when it applies.
+
+The following inputs are currently unsupported and cause exit status 1 without
+modifying that file:
+
+- multiple YAML documents;
+- a UTF-8 byte order mark;
+- custom YAML tags; and
+- anchors attached directly to scalar values.
+
+## Development
+
+After checking out the repository, install the selected Ruby and dependencies:
+
+```console
+$ rbenv install --skip-existing 3.3.5
+$ bundle install
+```
+
+Run the tests and Standard Ruby checks together:
+
+```console
+$ bundle exec rake
+```
+
+Build the gem with `bundle exec rake build` or install it locally with
+`bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/zeronosu77108/yamlfmt).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/exe/yamlfmt

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "yamlfmt"
+
+exit Yamlfmt::CLI.start(ARGV)

data/lib/yamlfmt/cli.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "pathname"
+
+module Yamlfmt
+  class CLI
+    INIT_CONFIG = <<~YAML
+      # .yamlfmt.yml
+      rules:
+        trailing-whitespace: true
+        final-newline: true
+        blank-lines:
+          max: 1
+        unnecessary-quotes: true
+
+      exclude:
+        - vendor
+        - node_modules
+    YAML
+
+    def self.start(argv, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd)
+      new(stdout:, stderr:, cwd:).run(argv)
+    end
+
+    def initialize(stdout:, stderr:, cwd:, processor: Processor.new, diff: UnifiedDiff.new)
+      @stdout = stdout
+      @stderr = stderr
+      @cwd = File.expand_path(cwd)
+      @processor = processor
+      @diff = diff
+    end
+
+    def run(argv)
+      options, paths, parser = parse(argv)
+      return print_help(parser) if options[:help]
+      return print_version if options[:version]
+      return initialize_config(options, paths) if options[:init]
+
+      validate_modes!(options)
+      process_files(options, paths)
+    rescue OptionParser::ParseError, ConfigError, PathError => error
+      @stderr.puts("yamlfmt: #{error.message}")
+      1
+    end
+
+    private
+
+    def parse(argv)
+      options = {fix: false, diff: false, init: false, color: true}
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: yamlfmt [options] [paths...]"
+        opts.on("--fix", "Rewrite files in place") { options[:fix] = true }
+        opts.on("--diff", "Print a unified diff without rewriting files") { options[:diff] = true }
+        opts.on("--init", "Create .yamlfmt.yml in the current directory") { options[:init] = true }
+        opts.on("--no-color", "Disable colored output") { options[:color] = false }
+        opts.on("--version", "Print the version") { options[:version] = true }
+        opts.on("-h", "--help", "Print this help") { options[:help] = true }
+      end
+      paths = parser.permute!(argv.dup)
+      [options, paths, parser]
+    end
+
+    def validate_modes!(options)
+      raise OptionParser::InvalidOption, "--fix and --diff cannot be used together" if options[:fix] && options[:diff]
+    end
+
+    def initialize_config(options, paths)
+      if options[:fix] || options[:diff] || !paths.empty?
+        raise OptionParser::InvalidOption, "--init cannot be combined with formatting options or paths"
+      end
+
+      path = File.join(@cwd, Config::FILE_NAME)
+      raise ConfigError, "#{Config::FILE_NAME} already exists" if File.exist?(path)
+
+      File.write(path, INIT_CONFIG)
+      @stdout.puts("Created #{Config::FILE_NAME}")
+      0
+    end
+
+    def process_files(options, paths)
+      config = Config.load(cwd: @cwd)
+      config.warnings.each { |warning| warn_message(warning) }
+      rules = RulePlan.new.call(config)
+      files = FileFinder.new(cwd: @cwd, exclude: config.exclude).call(paths)
+      state = {
+        error: false,
+        issues: 0,
+        autocorrectable: 0,
+        corrected: 0,
+        corrected_files: 0,
+        remaining: 0,
+        failed_files: 0
+      }
+
+      files.each do |path|
+        process_file(path, rules, options, state)
+      end
+
+      print_summary(files.length, state, fix: options[:fix]) unless options[:diff]
+
+      return 1 if state[:error] || state[:remaining].positive?
+      return 0 if options[:fix]
+
+      state[:issues].positive? ? 1 : 0
+    end
+
+    def process_file(path, rules, options, state)
+      autocorrectable = 0
+      source = File.binread(path).force_encoding(Encoding::UTF_8)
+      result = @processor.call(source, path:, rules:)
+      display_path = display_path(path)
+      result.warnings.each { |warning| warn_message("#{display_path}: #{warning}") }
+      autocorrectable = result.findings.count(&:autocorrectable?)
+      state[:issues] += result.findings.length
+      state[:autocorrectable] += autocorrectable
+
+      if options[:diff]
+        print_diff(result, display_path, options)
+        print_findings(result, display_path, findings: result.findings.reject(&:autocorrectable?))
+      else
+        print_findings(result, display_path)
+      end
+
+      if options[:fix]
+        state[:remaining] += result.findings.length - autocorrectable
+
+        if result.changed?
+          File.binwrite(path, result.formatted_source)
+          state[:corrected] += autocorrectable
+          state[:corrected_files] += 1
+        else
+          state[:remaining] += autocorrectable
+        end
+      end
+    rescue Error, SystemCallError => error
+      @stderr.puts("#{display_path(path)}: #{error.message}")
+      state[:error] = true
+      state[:remaining] += autocorrectable if options[:fix]
+      state[:failed_files] += 1
+    end
+
+    def print_summary(file_count, state, fix:)
+      @stdout.puts if state[:issues].positive?
+
+      parts = ["#{count(file_count, "file")} inspected"]
+      if state[:issues].zero?
+        parts << "no issues found"
+      else
+        parts << "#{count(state[:issues], "issue")} found"
+        if fix
+          parts << corrected_summary(state)
+          parts << remaining_summary(state[:remaining]) if state[:remaining].positive?
+        else
+          parts << "#{state[:autocorrectable]} autocorrectable"
+        end
+      end
+      parts << "#{count(state[:failed_files], "file")} failed" if state[:failed_files].positive?
+
+      @stdout.puts(parts.join(", "))
+    end
+
+    def corrected_summary(state)
+      return "0 corrected" if state[:corrected].zero?
+
+      "#{state[:corrected]} corrected in #{count(state[:corrected_files], "file")}"
+    end
+
+    def remaining_summary(number)
+      "#{count(number, "issue")} #{(number == 1) ? "remains" : "remain"}"
+    end
+
+    def count(number, noun)
+      "#{number} #{noun}#{"s" unless number == 1}"
+    end
+
+    def print_findings(result, display_path, findings: result.findings)
+      findings.each do |finding|
+        line, column = result.document.line_and_column(finding.range.start_offset)
+        @stdout.puts("#{display_path}:#{line}:#{column}: #{finding.rule_id} #{finding.message}")
+      end
+    end
+
+    def print_diff(result, display_path, options)
+      return unless result.changed?
+
+      output = @diff.call(result.source, result.formatted_source, path: display_path)
+      @stdout.write(colorize_diff(output, options))
+    end
+
+    def colorize_diff(output, options)
+      return output unless options[:color] && @stdout.respond_to?(:tty?) && @stdout.tty?
+
+      output.lines.map do |line|
+        case line
+        when /\A\+(?!\+\+)/ then "\e[32m#{line}\e[0m"
+        when /\A-(?!--)/ then "\e[31m#{line}\e[0m"
+        when /\A@@/ then "\e[36m#{line}\e[0m"
+        else line
+        end
+      end.join
+    end
+
+    def display_path(path)
+      relative = Pathname(File.expand_path(path)).relative_path_from(Pathname(@cwd)).to_s
+      return File.expand_path(path) if relative == ".." || relative.start_with?("../")
+
+      relative
+    rescue ArgumentError
+      File.expand_path(path)
+    end
+
+    def warn_message(message)
+      @stderr.puts("warning: #{message}")
+    end
+
+    def print_help(parser)
+      @stdout.puts(parser)
+      0
+    end
+
+    def print_version
+      @stdout.puts(Yamlfmt::VERSION)
+      0
+    end
+  end
+end

data/lib/yamlfmt/config.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "psych"
+
+module Yamlfmt
+  class Config
+    FILE_NAME = ".yamlfmt.yml"
+    TOP_LEVEL_KEYS = %w[rules exclude].freeze
+
+    attr_reader :exclude, :warnings, :path
+
+    def self.load(cwd: Dir.pwd)
+      path = File.join(File.expand_path(cwd), FILE_NAME)
+      return new({}, path:) unless File.file?(path)
+
+      source = File.binread(path).force_encoding(Encoding::UTF_8)
+      raise ConfigError, "#{path}: configuration must be valid UTF-8" unless source.valid_encoding?
+
+      data = Psych.safe_load(source, filename: path, aliases: false) || {}
+      new(data, path:)
+    rescue Psych::Exception, SystemCallError => error
+      raise ConfigError, "#{path}: #{error.message}"
+    end
+
+    def initialize(data, path: File.join(Dir.pwd, FILE_NAME))
+      raise ConfigError, "configuration root must be a mapping" unless data.is_a?(Hash)
+
+      @path = path
+      @warnings = []
+      warn_unknown_top_level_keys(data)
+      @rule_options = parse_rules(fetch(data, "rules", {})).freeze
+      @exclude = parse_exclude(fetch(data, "exclude", [])).freeze
+      @warnings.freeze
+    end
+
+    def options_for(rule_class)
+      value = @rule_options.fetch(rule_class.rule_id, {})
+      return nil if value == false
+
+      value
+    end
+
+    private
+
+    def parse_rules(rules)
+      raise ConfigError, "rules must be a mapping" unless rules.is_a?(Hash)
+
+      rules.each_with_object({}) do |(id, value), result|
+        id = id.to_s
+        unless Rule::Registry.ids.include?(id)
+          @warnings << "unknown rule: #{id}"
+          next
+        end
+
+        result[id] = parse_rule_value(Rule::Registry.fetch(id), value)
+      end
+    end
+
+    def parse_rule_value(rule_class, value)
+      return false if value == false
+      return {} if value == true
+      raise ConfigError, "#{rule_class.rule_id} must be true, false, or a mapping" unless value.is_a?(Hash)
+
+      defaults = rule_class.default_config
+      value.each_with_object({}) do |(key, option_value), options|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ConfigError, "option names for #{rule_class.rule_id} must be strings or symbols"
+        end
+
+        key = key.to_sym
+        unless defaults.key?(key)
+          @warnings << "unknown option for #{rule_class.rule_id}: #{key}"
+          next
+        end
+
+        options[key] = option_value
+      end
+    end
+
+    def parse_exclude(exclude)
+      raise ConfigError, "exclude must be a list" unless exclude.is_a?(Array)
+
+      exclude.map do |pattern|
+        raise ConfigError, "exclude entries must be non-empty strings" unless pattern.is_a?(String) && !pattern.empty?
+        raise ConfigError, "exclude entries must be relative paths" if pattern.start_with?("/")
+        raise ConfigError, "exclude negation is not supported" if pattern.start_with?("!")
+
+        normalized = pattern.delete_prefix("./").delete_suffix("/")
+        components = normalized.split("/")
+        if normalized.empty? || components.include?("..")
+          raise ConfigError, "exclude entries must stay within the current directory"
+        end
+
+        normalized
+      end
+    end
+
+    def warn_unknown_top_level_keys(data)
+      data.each_key do |key|
+        @warnings << "unknown configuration key: #{key}" unless TOP_LEVEL_KEYS.include?(key.to_s)
+      end
+    end
+
+    def fetch(hash, key, default)
+      return hash[key] if hash.key?(key)
+      return hash[key.to_sym] if hash.key?(key.to_sym)
+
+      default
+    end
+  end
+end

data/lib/yamlfmt/corrector.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Yamlfmt
+  class Corrector
+    def call(source, findings)
+      edits = normalize(findings)
+      validate_ranges!(source, edits)
+
+      edits.sort_by { |edit| [edit.range.start_offset, edit.range.end_offset] }.reverse_each.reduce(source.dup) do |result, edit|
+        before = result.byteslice(0, edit.range.start_offset)
+        after = result.byteslice(edit.range.end_offset, result.bytesize - edit.range.end_offset)
+        "#{before}#{edit.replacement}#{after}"
+      end
+    end
+
+    private
+
+    def normalize(findings)
+      pairs = findings.filter_map { |finding| [finding, finding.edit] if finding.edit }
+      unique_pairs = pairs.uniq { |_, edit| [edit.range, edit.replacement] }
+      redundant = {}
+
+      sorted_pairs = unique_pairs.sort_by { |_, edit| [edit.range.start_offset, edit.range.end_offset] }
+
+      sorted_pairs.each_with_index do |left, index|
+        left_finding, left_edit = left
+        ((index + 1)...sorted_pairs.length).each do |right_index|
+          right = sorted_pairs[right_index]
+          right_finding, right_edit = right
+          break if past_overlap_window?(left_edit, right_edit)
+
+          next unless left_edit.range.overlaps?(right_edit.range)
+
+          if redundant_deletion?(left_edit, right_edit)
+            redundant[right.object_id] = true
+          elsif redundant_deletion?(right_edit, left_edit)
+            redundant[left.object_id] = true
+          else
+            raise ConflictError, [left_finding, right_finding]
+          end
+        end
+      end
+
+      unique_pairs.reject { |pair| redundant[pair.object_id] }.map(&:last)
+    end
+
+    def past_overlap_window?(left_edit, right_edit)
+      left_range = left_edit.range
+      right_range = right_edit.range
+
+      if left_range.empty?
+        right_range.start_offset > left_range.start_offset
+      else
+        right_range.start_offset >= left_range.end_offset
+      end
+    end
+
+    def redundant_deletion?(outer, inner)
+      outer.replacement.empty? && inner.replacement.empty? && outer.range.cover?(inner.range)
+    end
+
+    def validate_ranges!(source, edits)
+      invalid = edits.find { |edit| edit.range.end_offset > source.bytesize }
+      raise ArgumentError, "edit range is outside the source" if invalid
+    end
+  end
+end