samagotchi 0.149.0 → 0.150.0

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -4,7 +4,11 @@ require "fileutils"
 require_relative "installer"
 require_relative "provenance"
 require_relative "manifest"
+require_relative "index_updater"
+require_relative "memory_files"
 require_relative "merger"
+require_relative "remerge"
+require_relative "trash"
 require_relative "../log"
 
 module Samagotchi
@@ -16,8 +20,9 @@ module Samagotchi
     # (~/.config/samagotchi/memories) on first Engine creation.
     #
     # A newer shipped version (manifest.yml) triggers a 3-way upgrade:
-    # fast-forward when not edited, keep when bundle unchanged, conflict keeps
-    # local edit with a warning. An older shipped version is left alone, so an
+    # fast-forward when not edited, keep when bundle unchanged, a clean text
+    # merge replaces the file, a real conflict keeps local edit with a warning.
+    # An older shipped version is left alone, so an
     # old checkout never downgrades the installed bundle; it says so once.
     module SystemBundle
       BUNDLE_NAME = "samagotchi-system"
@@ -29,12 +34,17 @@ module Samagotchi
       module_function
 
       # What sync did (or, with dry_run, would do). status is :installed,
-      # :updated, :restored (missing files put back), :up_to_date,
+      # :updated, :restored (missing files put back), :merged (a file marked
+      # conflict merged at the same version, Remerge), :up_to_date,
       # :newer_installed (left as is), :skipped (SKIP_ENV or no shipped
-      # bundle) or :failed (error: says why); kept lists the files whose
-      # local edits conflicted with the update and were kept.
-      Result = Struct.new(:from, :to, :status, :kept, :warnings, :error, keyword_init: true) do
-        def changed? = %i[installed updated restored].include?(status)
+      # bundle) or :failed (error: says why); merged lists the files a text
+      # merge replaced (trash_copy says where the old ones went), behind each file
+      # that stays behind (FileStanding::Behind). ensure! says only what an upgrade
+      # left behind: a file that was already behind isn't news at every start.
+      Result = Struct.new(:from, :to, :status, :merged, :behind, :trash_copy, :warnings, :error, keyword_init: true) do
+        def changed? = %i[installed updated restored merged].include?(status)
+
+        def kept = Array(behind).map(&:file)
       end
 
       # Ensure the system bundle is installed and up-to-date.
@@ -48,13 +58,35 @@ module Samagotchi
         when :newer_installed
           with_lock { note_newer_installed(result.from, result.to) }
         end
-        result.kept.each do |file_key|
-          Log.info(:memory, "system_local_edit_kept", echo: "[samagotchi-system] kept local edit in #{file_key} (bundle v#{result.to} has update — run: chi bundle status #{BUNDLE_NAME} / chi bundle diff #{BUNDLE_NAME} #{file_key})", file: file_key.to_s)
+        unless result.merged.empty?
+          note = [FileStanding.merged_line(result.merged, result.to), result.trash_copy].compact.join("; ")
+          Log.info(:memory, "system_bundle_merged", echo: "[samagotchi-system] #{note}", files: result.merged.join(","), to: result.to.to_s)
+        end
+        if result.status == :updated
+          result.behind.each do |file|
+            Log.info(:memory, "system_file_behind", echo: "[samagotchi-system] #{file.line} (#{FileStanding.diff_hint(BUNDLE_NAME, file.file)})", file: file.file)
+          end
         end
         result.warnings.each { |w| Log.warn(:memory, "system_bundle_warning", echo: "[samagotchi-system] #{w}") }
         result.changed?
       end
 
+      # The merges no chi update has shown (MergeNote): ask before .sync, whose
+      # own merges its caller reports itself.
+      # @return [Array<FileStanding::MergeNote>]
+      def merge_notes
+        Provenance.new(name: BUNDLE_NAME).record&.merge_notes || []
+      rescue StandardError
+        []
+      end
+
+      # Those notes have been shown (Provenance#clear_merge_notes), under the lock.
+      def clear_merge_notes(notes, files: [])
+        with_lock { Provenance.new(name: BUNDLE_NAME).clear_merge_notes(notes, files: files) }
+      rescue StandardError
+        nil
+      end
+
       # Install, upgrade or repair the installed system bundle to match the
       # shipped one, under the lock. Never raises; logs nothing (ensure!
       # and chi update report the Result).
@@ -80,20 +112,29 @@ module Samagotchi
           elsif installed_newer?(from, to)
             # Running an older checkout/gem: never downgrade the user's system memories
             # (not even to restore a missing file). `chi self` shows installed vs shipped.
-            result(:newer_installed, from: from, to: to)
+            result(:newer_installed, from: from, to: to, behind: bundle.behind_files)
           elsif from != to
-            dry_run ? result(:updated, from: from, to: to, kept: conflicting(gem_manifest)) : upgrade_existing(from, to)
+            dry_run ? planned_update(gem_manifest, from, to) : upgrade_existing(from, to)
           else
             # Already at desired version — still verify files present (e.g. user deleted one)
-            verify_files_present(gem_manifest, from, dry_run)
+            # and retry the files marked conflict.
+            verified = verify_files_present(gem_manifest, from, dry_run)
+            next remerge(bundle, verified, dry_run) if verified.status == :up_to_date
+
+            verified.tap { |done| done.behind = Provenance.new(name: BUNDLE_NAME).record.behind_files }
           end
         end
+      rescue Installer::InstallError => e
+        result(:failed, error: e.message)
+      rescue SystemCallError => e
+        result(:failed, error: Trash.failure_message(e))
       rescue StandardError => e
         result(:failed, error: "ensure failed: #{e.class}: #{e.message}")
       end
 
-      def result(status, from: nil, to: nil, kept: [], warnings: [], error: nil)
-        Result.new(from: from, to: to, status: status, kept: kept, warnings: warnings, error: error)
+      def result(status, from: nil, to: nil, merged: [], behind: [], trash_copy: nil, warnings: [], error: nil)
+        Result.new(from: from, to: to, status: status, merged: merged, behind: behind, trash_copy: trash_copy,
+                   warnings: warnings, error: error)
       end
 
       # Parallel chi starts on one config dir take turns: the second one reads
@@ -149,45 +190,69 @@ module Samagotchi
       end
 
       # Installer handles fast_forward/keep/noop; a conflict keeps the local
-      # file, and its own "Conflict in" warning is left out (kept says it).
+      # file, and its own warning is left out (behind says it).
       def upgrade_existing(from, to)
         installer = upgrade_installer
         installer.run
-        kept = installer.conflicts.keys
-        warnings = installer.warnings.reject { |w| kept.any? { |k| w.start_with?("Conflict in #{k}:") } }
-        result(:updated, from: from, to: to, kept: kept, warnings: warnings)
+        behind = installer.behind
+        warnings = installer.warnings.reject { |w| behind.any? { |file| w.start_with?(file.line) } }
+        result(:updated, from: from, to: to, merged: installer.merged_files, behind: behind, trash_copy: installer.trash_copy_line, warnings: warnings)
       end
 
       # A file from the bundle missing on disk (the user deleted it) is put
-      # back via the Installer (which classifies it as :install), without a
-      # full reinstall.
+      # back, and nothing else: at the same version a checkout can carry other
+      # text, so no other file is merged here (Remerge has its guard), and a live
+      # session's guardrails, plugin and scripts stay where they are.
       def verify_files_present(gem_manifest, version, dry_run)
         target_dir = MemoryPaths.system_dir
-        missing = gem_manifest.files.keys.any? { |k| !File.exist?(File.join(target_dir, k)) }
-        return result(:up_to_date, from: version, to: version) unless missing
+        missing = MemoryFiles.select(GEM_BUNDLE_DIR, gem_manifest).reject { |key| File.exist?(File.join(target_dir, key)) }
+        return result(:up_to_date, from: version, to: version) if missing.empty?
         return result(:restored, from: version, to: version) if dry_run
 
-        upgrade_installer.run
-        result(:restored, from: version, to: version)
+        warnings = missing.filter_map { |key| restore_file(key, gem_manifest.file_descriptions[key]) }
+        result(:restored, from: version, to: version, warnings: warnings)
       end
 
-      # The files an upgrade would keep: installed by the bundle, edited
-      # here and changed in the shipped bundle (a dry run's kept).
-      def conflicting(gem_manifest)
+      # @return [String, nil] a warning: the file is in place, its index line isn't
+      def restore_file(key, description)
+        source = File.join(GEM_BUNDLE_DIR, key)
+        target = File.join(MemoryPaths.system_dir, key)
+        FileUtils.cp(source, target)
+        Provenance.new(name: BUNDLE_NAME).record_restored(key, source, description: description)
+        begin
+          IndexUpdater.update_index(SCOPE, key.delete_suffix(".md"), File.size(target), description, source: BUNDLE_NAME)
+          nil
+        rescue StandardError => e
+          "index.md: line for #{key.delete_suffix(".md")} not updated (#{e.message})"
+        end
+      end
+
+      # An up-to-date bundle's marked files, retried. No marks: nothing is read.
+      def remerge(bundle, verified, dry_run)
+        done = Remerge.new(name: BUNDLE_NAME, scope: SCOPE, target_dir: MemoryPaths.system_dir, source_dir: GEM_BUNDLE_DIR, record: bundle)
+                      .run(dry_run: dry_run)
+        status = done.merged.empty? ? :up_to_date : :merged
+        result(status, from: verified.from, to: verified.to, merged: done.merged, behind: done.behind, trash_copy: done.trash_copy, warnings: done.warnings)
+      end
+
+      # A dry run's answer for an upgrade: what it would merge and keep, among
+      # the files installed by the bundle that are edited here and changed in
+      # the shipped bundle. The manifest's files:, not MemoryFiles.select: see
+      # Merger::Upgrade#forecast.
+      def planned_update(gem_manifest, from, to)
         provenance = Provenance.new(name: BUNDLE_NAME)
         owned = provenance.record&.files&.keys || []
-        (gem_manifest.files.keys.map(&:to_s).sort & owned).select do |key|
-          Merger.classify(base_path: provenance.base_path(key), current_path: File.join(MemoryPaths.system_dir, key),
-                          incoming_path: File.join(GEM_BUNDLE_DIR, key)) == :conflict
-        end
+        forecast = Merger::Upgrade.new(provenance: provenance, target_dir: MemoryPaths.system_dir, source_dir: GEM_BUNDLE_DIR)
+                                  .forecast(gem_manifest.files.keys.map(&:to_s).sort & owned, version: to)
+        result(:updated, from: from, to: to, merged: forecast.merged, behind: forecast.behind)
       end
 
       def upgrade_installer
         Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true,
                       shipped_dir: File.dirname(GEM_BUNDLE_DIR))
       end
-      private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present,
-                           :upgrade_installer, :result, :conflicting
+      private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present, :restore_file, :remerge,
+                           :upgrade_installer, :result, :planned_update
     end
   end
 end

data/lib/samagotchi/memory_bundle/text_merge.rb

@@ -0,0 +1,399 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+require_relative "../git_env"
+
+module Samagotchi
+  module MemoryBundle
+    # The text merge of an upgrade: three texts in, the merged text or why
+    # there is none out. Writes nothing but its temp copies; Merger::Upgrade
+    # asks and Merger.write_merged writes.
+    #
+    # It runs `git merge-file`. git isn't a chi runtime dependency, so no git,
+    # or the macOS stand-in that would pop an install dialog, is a :failed
+    # result: the caller keeps the file. Any doubt about what git answered reads
+    # the same way, and markers never leave this module.
+    #
+    # A hunk under a Changelog heading unions, ours then theirs' new entries
+    # (#union?), when nothing in or around it could make it more than a list of
+    # entries both sides only added to: see Scan. Any other hunk is a real conflict.
+    module TextMerge
+      MARKER_SIZE = 20
+      OURS = "yours"
+      THEIRS = "bundle"
+      OPEN = "#{"<" * MARKER_SIZE} #{OURS}".freeze
+      SEPARATOR = ("=" * MARKER_SIZE).freeze
+      BASE = "base"
+      BASE_MARK = "#{"|" * MARKER_SIZE} #{BASE}".freeze
+      CLOSE = "#{">" * MARKER_SIZE} #{THEIRS}".freeze
+      # git merge-file's exit status: the conflicts, capped; 255 is its error.
+      MAX_COUNTED = 127
+
+      # Seconds git may take. It runs under SystemBundle's lock at every chi start.
+      TIMEOUT = 10
+
+      # Where macOS keeps the stand-in, and what says whether it is one.
+      APPLE_STUB = "/usr/bin/git"
+      XCODE_SELECT = "/usr/bin/xcode-select"
+
+      NO_GIT = "git not found"
+      STUB_GIT = "#{APPLE_STUB} needs the command line tools: xcode-select --install".freeze
+      NOT_TEXT = "a side isn't text"
+      UNREADABLE = "git's answer couldn't be read"
+      NO_BASE = "no recorded base"
+      RACED = "the file changed during the merge"
+      TIMED_OUT = "git took too long"
+
+      # heading: the title of the last heading before it, nil when a rule or
+      # underline came after that one. ours, base, theirs: its lines on each
+      # side. union: it passed Scan's rule.
+      Hunk = Data.define(:heading, :ours, :base, :theirs, :union) do
+        def union? = union
+      end
+
+      # status: :clean (text is the merged text, hunks the unioned ones),
+      # :conflict (hunks has at least one that doesn't union; no text) or
+      # :failed (why says why there is no answer).
+      Result = Data.define(:status, :text, :hunks, :why) do
+        def clean? = status == :clean
+      end
+
+      module_function
+
+      # @param base [String] the file as last installed
+      # @param ours [String] the file on disk
+      # @param theirs [String] the bundle's new file
+      # @return [Result]
+      def merge(base:, ours:, theirs:)
+        return failed(NOT_TEXT) if [base, ours, theirs].any? { |text| text.b.include?("\0") }
+
+        git = find_git
+        return failed(NO_GIT) unless git
+        return failed(STUB_GIT) if apple_stub?(git)
+
+        output, code = run_git(git, base, ours, theirs)
+        return failed(TIMED_OUT) if code == :timeout
+        return failed(UNREADABLE) if code.nil? || code > MAX_COUNTED
+
+        scan = Scan.new(output)
+        return failed(UNREADABLE) unless scan.read? && [scan.hunks.size, MAX_COUNTED].min == code && from_inputs?(scan.lines, base, ours, theirs)
+
+        if scan.clean?
+          Result.new(status: :clean, text: scan.text, hunks: scan.hunks, why: nil)
+        else
+          Result.new(status: :conflict, text: nil, hunks: scan.hunks, why: nil)
+        end
+      rescue SystemCallError => e
+        failed("git couldn't run: #{e.message}")
+      end
+
+      def failed(why) = Result.new(status: :failed, text: nil, hunks: [], why: why)
+
+      # What +theirs+ changed against +base+ and +ours+ hasn't got, section by
+      # section: what a file that kept its own text has missed. A conflict's hunks
+      # can't say that: the whole file stays, so a change git would have merged is
+      # missed too, and the one hunk may be a Changelog line beside a whole new
+      # section. A section the user already brought over by hand isn't missed, nor
+      # one the bundle took out and the user did too.
+      # A heading (as written, "## Steps") names its section, the deepest one; a
+      # Changelog comes last, being the least of it.
+      # @return [Array(Array<String>, Boolean)] the headings; whether text under
+      #   no heading changed
+      def changed_sections(base, theirs, ours)
+        before, after, held = [base, theirs, ours].map do |text|
+          # Where a section falls leaves blank lines of its own at the end.
+          Scan.new(text).sections.map { |heading, lines| [heading, lines.join.strip] }
+        end
+        headings = (after - before - held).map(&:first)
+        gone = (before - after).map(&:first) - after.map(&:first)
+        names = (headings + (gone & held.map(&:first))).uniq
+        unnamed = names.include?(nil)
+        changelog, named = names.compact.partition { |name| name.sub(/\A#+[ \t]*/, "").match?(Scan::CHANGELOG) }
+        [named + changelog, unnamed]
+      end
+
+      # Whether git's answer is made of the inputs' lines: anything else (an
+      # empty answer to non-empty inputs too) must never replace a memory.
+      def from_inputs?(lines, *inputs)
+        known = inputs.flat_map { |text| text.b.each_line.map(&:chomp) }.to_h { |line| [line, true] }
+        return known.empty? if lines.empty?
+
+        lines.all? { |line| known.key?(line.chomp) }
+      end
+
+      # The first executable git on PATH, nil without one.
+      def find_git(path: ENV.fetch("PATH", ""))
+        path.split(File::PATH_SEPARATOR).reject(&:empty?).map { |dir| File.join(dir, "git") }
+            .find { |file| File.file?(file) && File.executable?(file) }
+      end
+
+      # Whether +git+ is macOS's stand-in with no developer tools behind it:
+      # running it pops a dialog. Unknown counts as yes.
+      def apple_stub?(git)
+        return false unless darwin? && same_file?(git, APPLE_STUB)
+
+        dir, status = Open3.capture2e(XCODE_SELECT, "-p")
+        !(status.success? && File.directory?(dir.strip))
+      rescue SystemCallError
+        true
+      end
+
+      def darwin? = RUBY_PLATFORM.include?("darwin")
+
+      def same_file?(one, other)
+        File.identical?(one, other)
+      rescue SystemCallError
+        false
+      end
+
+      # Temp copies in a temp cwd, with nothing inherited that could point git
+      # at a repository or a config: this runs inside other tools' hooks, whose
+      # GIT_DIR once defeated the temp cwd.
+      # @return [Array(String, Integer)] stdout, the exit status (nil: killed;
+      #   :timeout: it passed TIMEOUT and was stopped)
+      def run_git(git, base, ours, theirs)
+        Dir.mktmpdir("chi-merge-") do |dir|
+          { OURS => ours, BASE => base, THEIRS => theirs }.each { |name, text| File.binwrite(File.join(dir, name), text) }
+          capture_git(git_env(dir), [git, "merge-file", "-p", "--diff3", "--marker-size=#{MARKER_SIZE}",
+                                     "-L", OURS, "-L", BASE, "-L", THEIRS, OURS, BASE, THEIRS], dir)
+        end
+      end
+
+      # In a process group of its own: /usr/bin/git may be a launcher with the
+      # real git as its child.
+      def capture_git(env, command, dir)
+        Open3.popen2(env, *command, chdir: dir, err: File::NULL, pgroup: true) do |stdin, stdout, wait|
+          stdin.close
+          stdout.binmode
+          reader = Thread.new { stdout.read }
+          unless wait.join(TIMEOUT)
+            stop_group(wait.pid)
+            reader.kill
+            next ["", :timeout]
+          end
+          [reader.value, wait.value.exitstatus]
+        end
+      end
+
+      def stop_group(pid)
+        Process.kill("KILL", -pid)
+      rescue SystemCallError
+        nil
+      end
+
+      def git_env(dir)
+        GitEnv::UNSET.merge("GIT_CONFIG_PARAMETERS" => nil, "GIT_CONFIG_COUNT" => nil,
+                            "GIT_CONFIG_GLOBAL" => File::NULL, "GIT_CONFIG_SYSTEM" => File::NULL, "GIT_CONFIG_NOSYSTEM" => "1",
+                            "GIT_CEILING_DIRECTORIES" => File.dirname(File.realpath(dir)))
+      end
+
+      # git's output, read a line at a time. Takes the markers out, keeps track
+      # of the last heading outside any hunk, code fence and HTML comment, and
+      # decides each hunk (D3a of the kept-edits plan). The rule is strict
+      # because the naive one merges real rules silently: a fenced "## Changelog"
+      # template would swallow what follows it, one hunk can span a Changelog
+      # line and a real section, and a paragraph after the entries is no entry.
+      # A hunk unions only when
+      #   - the last heading before it is titled exactly Changelog (or Change
+      #     log), at level 1 or 2, with no rule or underline after that heading
+      #     and nothing but list entries between it and the hunk;
+      #   - no fence or comment is open; and
+      #   - base, ours and theirs each hold only list entries, and both sides
+      #     still hold every entry of the base: both only added. An edited or
+      #     dropped entry is a decision, and so is a base heading both dropped.
+      # An entry is a list item and the lines indented deeper right under it,
+      # nested items too, none of which, indentation aside, is a heading, a rule
+      # or a fence; a blank line ends it. The union is ours, then the entries of
+      # theirs that ours doesn't have, compared whole.
+      # Marker lines that don't pair up (a user's line equal to one) mean the
+      # output can't be read at all.
+      class Scan
+        HEADING = /\A {0,3}(\#{1,6})(?:[ \t]|\z)/
+        RULE = /\A {0,3}(?:=+|-+|\*{3,}|_{3,}|([-*_])(?:[ \t]*\1){2,})[ \t]*\z/
+        FENCE = /\A {0,3}(`{3,}|~{3,})/
+        LIKE_HEADING = /\A {0,3}#/
+        CHANGELOG = /\Achange ?log\z/i
+        ITEM = /\A {0,3}(?:[-*+]|\d{1,9}[.)])[ \t]+\S/
+        ITEM_MORE = /\A(?: {2,}|\t)\S/
+        COMMENT_OPEN = "<!--"
+        COMMENT_CLOSE = "-->"
+        CHANGELOG_LEVEL = 2
+
+        attr_reader :hunks, :lines
+
+        # [heading as written (nil before the first), its lines], in order.
+        attr_reader :sections
+
+        def initialize(output)
+          @sections = [[nil, []]]
+          @hunks = []
+          @pieces = []
+          @lines = []
+          @heading = nil
+          @changelog = false
+          @in_item = false
+          @fence = nil
+          @comment = false
+          @read = read_lines(output.b.each_line)
+        end
+
+        def read? = @read
+
+        def clean? = @hunks.all?(&:union?)
+
+        def text = @pieces.join
+
+        private
+
+        # @return [Boolean] the markers paired up
+        def read_lines(lines)
+          state = :text
+          ours = base = theirs = nil
+          lines.each do |line|
+            bare = line.chomp
+            case state
+            when :text
+              return false if [BASE_MARK, CLOSE].include?(bare)
+
+              if bare == OPEN
+                ours = []
+                state = :ours
+              else
+                add_text(line, bare)
+              end
+            when :ours
+              return false if [OPEN, SEPARATOR, CLOSE].include?(bare)
+
+              if bare == BASE_MARK
+                base = []
+                state = :base
+              else
+                ours << line
+              end
+            when :base
+              return false if [OPEN, BASE_MARK, CLOSE].include?(bare)
+
+              if bare == SEPARATOR
+                theirs = []
+                state = :theirs
+              else
+                base << line
+              end
+            when :theirs
+              return false if [OPEN, BASE_MARK, SEPARATOR].include?(bare)
+
+              if bare == CLOSE
+                add_hunk(ours, base, theirs)
+                state = :text
+              else
+                theirs << line
+              end
+            end
+          end
+          state == :text
+        end
+
+        def add_text(line, bare)
+          @pieces << line
+          @lines << line
+          classify_text(bare)
+          @sections.last.last << line
+        end
+
+        def classify_text(bare)
+          return follow_fence(bare) if @fence || bare.match?(FENCE)
+          return follow_comment(bare) if @comment || bare.include?(COMMENT_OPEN)
+
+          if bare.match?(HEADING) then add_heading(bare)
+          elsif bare.match?(RULE) then @heading = nil
+          else follow_list(bare)
+          end
+        end
+
+        def add_heading(bare)
+          # Reports and the record take these: the scan is binary, and they need text.
+          @heading = text_of(bare.sub(/\A {0,3}\#{1,6}[ \t]*/, "").sub(/[ \t#:]*\z/, ""))
+          @changelog = bare[HEADING, 1].size <= CHANGELOG_LEVEL && @heading.match?(CHANGELOG)
+          @in_item = false
+          @sections << [text_of(bare.strip.sub(/[ \t#:]*\z/, "")), []]
+        end
+
+        # Whether the section so far is still nothing but list entries.
+        def follow_list(bare)
+          return @in_item = false if bare.strip.empty?
+
+          @in_item = bare.match?(ITEM) || (@in_item && more_of_entry?(bare))
+          @changelog = false unless @in_item
+        end
+
+        # An open fence closes on a line of its own character, at least as
+        # long, with nothing after it.
+        def follow_fence(bare)
+          @changelog = false
+          fence = bare[FENCE, 1]
+          return @fence = fence unless @fence
+          return unless fence && fence[0] == @fence[0] && fence.size >= @fence.size
+
+          @fence = nil if bare.strip == fence
+        end
+
+        def follow_comment(bare)
+          @changelog = false
+          after = @comment ? bare : bare[(bare.index(COMMENT_OPEN) + COMMENT_OPEN.size)..]
+          @comment = !after.include?(COMMENT_CLOSE)
+        end
+
+        def add_hunk(ours, base, theirs)
+          @lines.concat(ours, base, theirs)
+          union = union_of(ours, base, theirs)
+          @hunks << Hunk.new(heading: @heading, ours: ours, base: base, theirs: theirs, union: !union.nil?)
+          return unless union
+
+          @pieces.concat(union)
+          @in_item = true
+        end
+
+        # The union's lines, nil when this hunk isn't one.
+        def union_of(ours, base, theirs)
+          return nil if @fence || @comment || !@changelog || !@heading.to_s.match?(CHANGELOG)
+
+          ours_entries = entries(ours)
+          base_entries = entries(base)
+          theirs_entries = entries(theirs)
+          return nil unless ours_entries && base_entries && theirs_entries
+          return nil unless (base_entries - ours_entries).empty? && (base_entries - theirs_entries).empty?
+
+          ours + (theirs_entries - ours_entries).flatten
+        end
+
+        # The side's list entries, each a list of lines; nil when it holds
+        # anything else.
+        def entries(lines)
+          attached = false
+          lines.each_with_object([]) do |line, found|
+            bare = line.chomp
+            if bare.strip.empty?
+              attached = false
+            elsif structural?(bare.lstrip) then return nil
+            elsif attached && bare.match?(ITEM_MORE) && indent(bare) > indent(found.last.first) then found.last << line
+            elsif bare.match?(ITEM)
+              found << [line]
+              attached = true
+            else return nil
+            end
+          end
+        end
+
+        def more_of_entry?(bare) = bare.match?(ITEM_MORE) && !structural?(bare.lstrip)
+
+        def indent(line) = line[/\A[ \t]*/].size
+
+        # As UTF-8, what isn't valid replaced: a heading is for reading.
+        def text_of(bytes) = bytes.dup.force_encoding(Encoding::UTF_8).scrub
+
+        def structural?(text) = text.match?(LIKE_HEADING) || text.match?(RULE) || text.match?(FENCE)
+      end
+    end
+  end
+end