bundle_alphabetically 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78e0866723d9bd83432fbb9477da3181b8159e1d72c57e128b3d1d2d208bc0d4
+  data.tar.gz: 5d2b084f5b292ed3fccf27313171ba00a1b57faa908c1ef617b83049ec0f0a7a
+SHA512:
+  metadata.gz: 0bb63059900621a58af5939cb6a97cd3960e5c66b574978ff25763fa8ecc983a75b502eda3640aad95c19296e3170f6247084566f5c4d35793f1c5cb207a63c9
+  data.tar.gz: 80fe2cc000aec12bcfde0cff162184a8e0a16e2e1db6f3ee27f0dd7c75e4ea9a02f7ac9fddbc57e4bca5d318f5c163d9d720a97f7d2deb289954f9cd92fbf114

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-12-11
+
+### Added
+- Initial release
+- Automatic sorting after `bundle add`/`bundle install`
+- Manual `bundle sort_gemfile` command
+- `--check` flag for CI verification
+- Sorts gems alphabetically within each group
+- Preserves group structure, comments, and formatting

data/README.md

@@ -0,0 +1,95 @@
+## bundle_alphabetically
+
+**bundle_alphabetically** is a Bundler plugin that keeps your `Gemfile` organized by alphabetizing `gem` declarations **within each group**.
+
+- **Automatic mode**: after `bundle add` / `bundle install`, it rewrites your `Gemfile` so gems are sorted alphabetically inside each group.
+- **Manual mode**: run `bundle sort_gemfile` whenever you want to clean things up (with an optional `--check` for CI).
+
+### Installation
+
+Install the plugin from RubyGems:
+
+```bash
+bundle plugin install bundle_alphabetically
+```
+
+Or add it to your `Gemfile` and install:
+
+```ruby
+plugin "bundle_alphabetically"
+```
+
+```bash
+bundle install
+```
+
+For development, you can install from a local checkout:
+
+```bash
+cd /path/to/bundle_alphabetically
+bundle plugin install bundle_alphabetically --path .
+```
+
+Once installed, Bundler will load `plugins.rb` and register the command and hooks.
+
+### What it does
+
+- Sorts `gem` entries alphabetically by name **within each context**:
+  - top-level (no group)
+  - each `group :name do ... end` block, separately
+- Preserves:
+  - non-gem lines like `source`, `ruby`, `plugin`, `path`, etc.
+  - group block structure and indentation
+  - comments and most surrounding blank lines
+  - multi-line `gem` declarations (e.g. options hashes split across lines)
+
+It operates on the current `Bundler.default_gemfile` and rewrites it in place.
+
+### Automatic sorting (hook)
+
+The plugin registers an `after-install-all` hook:
+
+- After a successful install (including `bundle add`), Bundler calls into `bundle_alphabetically`.
+- The plugin sorts the `Gemfile` and prints a short message like:
+  - `Gemfile gems alphabetized by bundle_alphabetically`
+
+If the `Gemfile` is already sorted, it does nothing.
+
+If it encounters an error parsing the `Gemfile`, it raises a `Bundler::BundlerError` and reports a message via `Bundler.ui.error`, but leaves the file unchanged.
+
+### Manual command
+
+The plugin adds a `bundle sort_gemfile` command via `Bundler::Plugin::API`:
+
+```bash
+bundle sort_gemfile
+```
+
+- Sorts the current `Gemfile` in place using the same rules as the hook.
+- Prints `Gemfile already sorted` if no changes were needed.
+
+For CI, you can use `--check` (or `-c`) to verify sorting without modifying the file:
+
+```bash
+bundle sort_gemfile --check
+```
+
+In `--check` mode:
+
+- Exit successfully if the `Gemfile` is already sorted.
+- Raise `Bundler::BundlerError` (non-zero exit) if changes would be required.
+
+### Limitations
+
+- Designed for conventional `Gemfile`s:
+  - top-level `gem` calls and `group ... do` blocks
+  - straightforward multi-line `gem` entries
+- It does **not** attempt to fully evaluate arbitrary Ruby or heavy metaprogramming inside the `Gemfile`.
+
+If you have an unusually dynamic `Gemfile` and hit issues, you can temporarily uninstall the plugin with:
+
+```bash
+bundler plugin uninstall bundle_alphabetically
+```
+
+

data/lib/bundle_alphabetically/common.rb

@@ -0,0 +1,71 @@
+module BundleAlphabetically
+  module Common
+    def collect_gem_entry(lines, start_index, body_end_index = nil)
+      body_end_index ||= lines.length - 1
+      formatting_lines = []
+
+      while start_index <= body_end_index && start_index < lines.length && blank_or_comment?(lines[start_index])
+        formatting_lines << lines[start_index]
+        start_index += 1
+      end
+
+      if start_index > body_end_index || start_index >= lines.length
+        return [formatting_lines, [], start_index]
+      end
+
+      entry_lines = [lines[start_index]]
+      base_indent = indent_of(lines[start_index])
+      i = start_index + 1
+
+      while i <= body_end_index && i < lines.length
+        line = lines[i]
+        stripped = line.lstrip
+        indent = indent_of(line)
+
+        break if stripped.empty?
+
+        if blank_or_comment?(line) && indent <= base_indent
+          break
+        end
+
+        if indent <= base_indent && starter_keyword?(stripped)
+          break
+        end
+
+        entry_lines << line
+        i += 1
+      end
+
+      [formatting_lines, entry_lines, i]
+    end
+
+    def blank_or_comment?(line)
+      line.strip.empty? || line.strip.start_with?("#")
+    end
+
+    def indent_of(line)
+      line[/\A[ \t]*/].size
+    end
+
+    def starter_keyword?(stripped)
+      stripped.start_with?(
+        "gem ", "gem(", "group ", "group(", "source ", "source(", "ruby ",
+        "ruby(", "path ", "path(", "plugin ", "plugin(", "platforms ",
+        "platforms(", "end", "gemspec", "git ", "git(", "if ", "else",
+        "local_gemfile", "instance_eval", "rack_version"
+      )
+    end
+
+    def gem_start?(line)
+      return false if blank_or_comment?(line)
+      line.lstrip.start_with?("gem ") || line.lstrip.start_with?("gem(")
+    end
+
+    def extract_gem_name(line)
+      stripped = line.lstrip
+      match = stripped.match(/\Agem\s+["']([^"']+)["']/)
+      match && match[1]
+    end
+  end
+end
+

data/lib/bundle_alphabetically/gemfile_sorter.rb

@@ -0,0 +1,174 @@
+require "bundler"
+require "set"
+
+require_relative "group"
+require_relative "common"
+
+module BundleAlphabetically
+  class GemfileSorter
+    extend Common
+
+    class CheckFailed < Bundler::BundlerError
+      def status_code
+        1
+      end
+    end
+
+    class << self
+      attr_accessor :groups, :lines
+
+      def run!(check: false, io: $stdout)
+        gemfile = Bundler.default_gemfile
+
+        unless gemfile && File.file?(gemfile.to_s)
+          raise Bundler::BundlerError, "Gemfile not found at #{gemfile}"
+        end
+
+        path = gemfile.to_s
+        original = File.read(path)
+        sorted = sort_contents(original)
+
+        if original == sorted
+          io.puts "Gemfile already sorted" unless check
+          return
+        end
+
+        if check
+          raise CheckFailed, "Gemfile is not alphabetically sorted"
+        else
+          File.write(path, sorted)
+          io.puts "Gemfile gems alphabetized by bundle_alphabetically"
+        end
+      end
+
+      def sort_contents(contents)
+        @groups = []
+        @lines = contents.lines
+        return contents if lines.empty?
+
+        collect_groups!
+        sort_groups!
+
+        lines.join
+      end
+
+      private
+
+      def sort_groups!
+        groups.each do |group|
+          group.sort!
+          lines[group.body_start_index..group.body_end_index] = group.body if group.body
+        end
+      end
+
+      def collect_groups!
+        i = 0
+        current_group_start = nil
+
+        while i < lines.size
+          # Peek ahead of blanks/comments to find next group
+          peek_index = i
+          while peek_index < lines.size && blank_or_comment?(lines[peek_index])
+            peek_index += 1
+          end
+
+          if peek_index < lines.size && group_header?(lines[peek_index])
+
+            # Close current group
+            if current_group_start
+              process_gem_block(current_group_start, peek_index - 1)
+              current_group_start = nil
+            end
+
+            i = process_group_block(peek_index)
+            next
+          end
+
+          # 3. Not a group. Consume the next "entry" (gem, source, ruby, etc.)
+          _, entry_lines, next_index = collect_gem_entry(lines, i)
+
+          if gem_entry?(entry_lines)
+            current_group_start ||= i
+          else
+            # We hit something that isn't a gem and isn't a group (e.g. source, ruby version, etc.)
+            process_gem_block(current_group_start, i - 1) if current_group_start
+            current_group_start = nil
+          end
+
+          i = next_index
+        end
+
+        # Finish any trailing gem block
+        process_gem_block(current_group_start, lines.size - 1) if current_group_start
+      end
+
+      def process_group_block(header_index)
+        end_index = find_matching_end(lines, header_index)
+
+        # If we can't find an end, just skip this line
+        return header_index + 1 unless end_index
+
+        @groups << Group.new(lines, {
+          header:     header_index,
+          body_start: header_index + 1,
+          body_end:   end_index - 1,
+          end:        end_index
+        })
+
+        end_index + 1
+      end
+
+      def group_header?(line)
+        stripped = line.lstrip
+        stripped.start_with?("group ") || stripped.start_with?("group(")
+      end
+
+      def find_matching_end(lines, header_index)
+        header_indent = indent_of(lines[header_index])
+        i = header_index + 1
+
+        while i < lines.length
+          line = lines[i]
+          stripped = line.lstrip
+          indent = indent_of(line)
+
+          if group_header?(line) && indent > header_indent
+            nested_end = find_matching_end(lines, i)
+            return nil unless nested_end
+            i = nested_end + 1
+            next
+          end
+
+          if stripped.start_with?("end") && indent == header_indent
+            return i
+          end
+
+          i += 1
+        end
+
+        nil
+      end
+
+      def gem_entry?(entry_lines)
+        entry_lines.any? && gem_start?(entry_lines.first)
+      end
+
+      def process_gem_block(start_index, end_index)
+        return unless start_index
+
+        create_and_sort_group(lines, start_index, end_index)
+      end
+
+      def create_and_sort_group(lines, start_index, end_index)
+        return if start_index >= end_index
+
+        @groups << Group.new(lines, {
+          header:     start_index,
+          body_start: start_index,
+          body_end:   end_index,
+          end:        end_index
+        })
+      end
+    end
+  end
+end

data/lib/bundle_alphabetically/group.rb

@@ -0,0 +1,148 @@
+require_relative "common"
+
+class BundleAlphabetically::Group
+  include BundleAlphabetically::Common
+
+  attr_accessor :header_index, :body_start_index, :body_end_index, :end_index, :unsortable, :entries, :lines, :trailing_lines, :leading_lines
+
+  def initialize(lines, indices = {})
+    @lines            = lines
+    @header_index     = indices[:header]
+    @body_start_index = indices[:body_start]
+    @body_end_index   = indices[:body_end]
+    @end_index        = indices[:end]
+    @entries          = []
+    @unsortable       = false
+    @trailing_lines   = []
+    @leading_lines    = []
+  end
+
+  def sort!
+    return unless valid?
+
+    find_entries
+    sort_entries!
+  end
+
+  def sort_entries!
+    return if unsortable || entries.empty?
+
+    collect_trailing_lines
+    collect_leading_lines
+    normalize_formatting_lines
+
+    sorted_entries = entries.sort_by { |e| e[:name].downcase }
+
+    self.body = rebuild_body(sorted_entries)
+  end
+
+  def rebuild_body(sorted_entries)
+    new_body = []
+
+    leading_lines.each { |line| new_body << line } if !leading_separator_exists?
+
+    sorted_entries.each_with_index do |entry, index|
+      # Always move leading blanks for the first entry
+      move_leading_blanks = entry[:formatting_lines].empty? || index.zero?
+
+      new_body = append_entry(entry, new_body, move_leading_blanks)
+    end
+
+    trailing_lines.each { |line| new_body << line } if trailing_lines.any?
+
+    new_body
+  end
+
+  # If an entry has no comments/formatting (just a plain gem), treat blanks as trailing
+  # separators by placing them after the entry. This keeps "section" spacing stable when
+  # gems reorder.
+  def append_entry(entry, new_body, move_leading_blanks)
+    leading_blanks = entry[:leading_blanks] || []
+
+    leading_blanks.each { |line| new_body << line } unless move_leading_blanks
+
+    entry[:formatting_lines].each { |line| new_body << line }
+    entry[:lines].each { |line| new_body << line }
+
+    leading_blanks.each { |line| new_body << line } if move_leading_blanks
+
+    new_body
+  end
+
+  def normalize_formatting_lines
+    entries.each do |entry|
+      entry[:leading_blanks] = []
+      next unless entry[:formatting_lines]&.any?
+
+      while entry[:formatting_lines].any? && entry[:formatting_lines].first.strip.empty?
+        entry[:leading_blanks] << entry[:formatting_lines].shift
+      end
+    end
+  end
+
+  # If the group starts with blank lines (e.g. spacing after `plugin` / `gemspec`),
+  # keep them at the start of the group rather than attaching them to a gem
+  # that might move during sorting.
+  def collect_leading_lines
+    return unless entries.first[:formatting_lines]&.any?
+
+    while entries.first[:formatting_lines].any? && entries.first[:formatting_lines].first.strip.empty?
+      @leading_lines << entries.first[:formatting_lines].shift
+    end
+  end
+
+  # Don't sort trailing comments and blank lines
+  def collect_trailing_lines
+    return unless entries.last[:name].empty? && entries.last[:lines].empty?
+
+    @trailing_lines = entries.pop[:formatting_lines]
+  end
+
+  # If we're starting from the top or the prior group ended with a blank line,
+  # we don't need to move leading blank lines before the first entry.
+  def leading_separator_exists?
+    !body_start_index.positive? || lines[body_start_index - 1].strip.empty?
+  end
+
+  def find_entries
+    index = body_start_index
+
+    while index <= body_end_index
+      formatting_lines, entry_lines, after_entry_index = collect_gem_entry(lines, index, body_end_index)
+
+      break if formatting_lines.empty? && entry_lines.empty?
+
+      # If we haven't advanced, force a break to avoid infinite loops
+      break if after_entry_index == index
+
+      if entry_lines.any?
+        name = extract_gem_name(entry_lines.first)
+
+        if name
+          entries << { name: name, lines: entry_lines, formatting_lines: formatting_lines }
+        else
+          @unsortable = true
+          entries << { name: "", lines: entry_lines, formatting_lines: formatting_lines }
+        end
+      else
+        # Trailing formatting lines
+        entries << { name: "", lines: [], formatting_lines: formatting_lines }
+        @unsortable = true unless formatting_lines.all? { |l| l.strip.empty? }
+      end
+
+      index = after_entry_index
+    end
+  end
+
+  def valid?
+    body_end_index > body_start_index
+  end
+
+  def body
+    @body ||= lines[body_start_index..body_end_index]
+  end
+
+  def body=(new_lines)
+    @body = new_lines
+  end
+end

data/lib/bundle_alphabetically/version.rb

@@ -0,0 +1,5 @@
+module BundleAlphabetically
+  VERSION = "0.1.0"
+end
+
+

data/lib/bundle_alphabetically.rb

@@ -0,0 +1,25 @@
+require "bundler"
+require "bundler/plugin/api"
+
+require_relative "bundle_alphabetically/version"
+require_relative "bundle_alphabetically/gemfile_sorter"
+require_relative "bundle_alphabetically/group"
+
+module BundleAlphabetically
+  class SortGemfileCommand < Bundler::Plugin::API
+    command "sort_gemfile"
+
+    def exec(_command, args)
+      check = args.include?("--check") || args.include?("-c")
+      GemfileSorter.run!(check: check)
+    end
+  end
+end
+
+Bundler::Plugin.add_hook("after-install-all") do |_dependencies|
+  begin
+    BundleAlphabetically::GemfileSorter.run!
+  rescue Bundler::BundlerError => e
+    Bundler.ui.error("bundle_alphabetically: #{e.message}")
+  end
+end

data/plugins.rb

@@ -0,0 +1,3 @@
+require_relative "lib/bundle_alphabetically"
+
+

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: bundle_alphabetically
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Elijah Rogers
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Bundler plugin that keeps your Gemfile organized by alphabetizing gem
+  declarations within each group automatically.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/bundle_alphabetically.rb
+- lib/bundle_alphabetically/common.rb
+- lib/bundle_alphabetically/gemfile_sorter.rb
+- lib/bundle_alphabetically/group.rb
+- lib/bundle_alphabetically/version.rb
+- plugins.rb
+homepage: https://github.com/elijahrogers/bundle_alphabetically
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/elijahrogers/bundle_alphabetically
+  changelog_uri: https://github.com/elijahrogers/bundle_alphabetically/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Bundler plugin that alphabetizes gem entries
+test_files: []