samagotchi 0.148.0 → 0.150.0

data/lib/samagotchi/memory_bundle/installed_bundle.rb

@@ -1,17 +1,27 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json"
+require_relative "../memory_paths"
 require_relative "bundle_hook"
 require_relative "plugin_ref"
 
 module Samagotchi
   module MemoryBundle
+    # Only what reports on an edited file needs it.
+    autoload :FileStanding, File.expand_path("file_standing", __dir__)
+
     # An installed bundle's record, as Provenance#write keeps it in
     # <bundles>/<name>/manifest.json. Reading is tolerant: an older record
     # lacks keys a newer chi writes, and a key that is missing or of the
     # wrong shape reads as empty (nil for the optional strings and lists).
     #
-    #   files       file key ("x.md") => { checksum:, conflict:, description: } (symbol keys)
+    #   files       file key ("x.md") => { checksum:, conflict:, incoming_sha:, legacy_base:, why:, missed:, missed_places:,
+    #               description: } (symbol keys);
+    #               incoming_sha: the bundle text a conflict mark speaks of, nil on an older mark;
+    #               legacy_base: true on an older mark that has since got its incoming_sha (.legacy_mark?);
+    #               why, missed, missed_places: FileStanding::Behind's, nil on an older mark;
+    #               merged_version, merged_at, merged_trash: a merge no report has shown (Provenance#note_merged)
     #   hooks       basename => BundleHook
     #   guardrails  basename => recorded sha256 ("" when none)
     #   scripts     file name => recorded sha256 ("" when none)
@@ -45,6 +55,12 @@ module Samagotchi
         super(name: name, **OPTIONAL, **fields)
       end
 
+      # Whether a file's entry is a conflict mark from an older chi: no
+      # incoming_sha, or legacy_base. Such a mark's base may be the user's own
+      # text (0.149 took it for a file with no base). Getting its digest later
+      # must not make it look new, so legacy_base stays until the mark goes.
+      def self.legacy_mark?(entry) = !!entry && entry[:conflict] == true && (entry[:legacy_base] == true || !entry[:incoming_sha])
+
       # The record at +path+, nil when there is none.
       # @raise [JSON::ParserError, SystemCallError] it doesn't read
       def self.read(name, path)
@@ -100,6 +116,51 @@ module Samagotchi
 
       def owns?(file_key) = files.key?(file_key.to_s)
 
+      # The plugin's file => its recorded sha256, as guardrails and scripts read.
+      def plugin_shas = plugin ? { plugin.file => plugin.sha256 } : {}
+
+      # The marked files that stay behind: one that isn't there is a missing file,
+      # and one with the bundle's bytes has nothing left to miss.
+      # @param target_dir [String, nil] where its files are; a scope this chi can't
+      #   resolve has none, and nothing is known of them
+      # @return [Array<FileStanding::Behind>]
+      def behind_files(target_dir = MemoryPaths.scope_dir(effective_scope))
+        return [] unless target_dir
+
+        files.filter_map { |key, entry| behind_entry(key, entry) if behind_file?(key, File.join(target_dir, key)) }
+      end
+
+      # FileStanding.behind? for this record's file. An older mark names no text,
+      # but a source still on disk holds it: level with that, it has missed nothing.
+      def behind_file?(key, path)
+        entry = files.fetch(key)
+        FileStanding.behind?(path, entry, incoming_sha: entry[:incoming_sha] || source_sha(key))
+      end
+
+      # The merges no chi update has shown yet.
+      # @return [Array<FileStanding::MergeNote>]
+      def merge_notes
+        files.filter_map do |key, entry|
+          next unless entry[:merged_version]
+
+          FileStanding::MergeNote.new(file: key, version: entry[:merged_version], at: entry[:merged_at], trash: entry[:merged_trash])
+        end
+      end
+
+      # The file's mark as a report reads it.
+      def behind_entry(key, entry = files.fetch(key))
+        FileStanding::Behind.new(file: key, version: version, why: entry[:why], missed: entry[:missed], places: entry[:missed_places],
+                                 unsure: !entry[:incoming_sha] && !entry[:why])
+      end
+
+      def source_sha(key)
+        path = File.join(source.to_s, key)
+        File.file?(path) ? Digest::SHA256.file(path).hexdigest : nil
+      rescue SystemCallError
+        nil
+      end
+      private :source_sha
+
       def needs? = needs.is_a?(Array) && !needs.empty?
 
       def context_providers? = context_providers.is_a?(Array) && !context_providers.empty?

data/lib/samagotchi/memory_bundle/installer.rb

@@ -34,6 +34,9 @@ module Samagotchi
 
       attr_reader :results, :warnings, :placeholder_warnings, :conflicts
 
+      # Each file this run left behind (FileStanding::Behind).
+      attr_reader :behind
+
       # prepared: the source already normalized (a PreparedSource, which the
       # Installer then owns and cleans up as its own); nil normalizes source.
       # shipped_dir: the bundles this chi ships (a bundle of their names
@@ -55,6 +58,9 @@ module Samagotchi
         @warnings = []
         @placeholder_warnings = []
         @conflicts = {}
+        @behind = []
+        @replaced = []
+        @outcomes = {}
         @overlays = []
         @trash = Trash.new(name)
       end
@@ -63,10 +69,16 @@ module Samagotchi
       # source (Installer#check_source), else nil.
       attr_reader :source_change
 
-      # Where an upgrade moved the files the bundle no longer ships (nil:
-      # none moved).
+      # Where this install moved the files the bundle no longer ships and
+      # copied the ones it overwrote (nil: none).
       def trash_dir = @trash.dir
 
+      # What it copied to the trash before overwriting, said once (nil: nothing).
+      def trash_copy_line = @trash.copy_line
+
+      # The files this run merged, the bundle's changes joined to the user's.
+      def merged_files = @results.select { |_, r| r[:status] == "merged" }.keys
+
       # The normalized source dir. An owned one (a git/zip/tar extract) is
       # removed after #run, or kept until #cleanup_source! when an upgrade
       # has conflicts (the agent step reads the incoming files); nil once
@@ -94,16 +106,7 @@ module Samagotchi
         check_source
         # A plain install over an installed bundle: summary points at upgrade.
         @reinstall = @existing && !@upgrade && !@force && !@dry_run
-        install_memories
-
-        installed = AssetInstaller.new(
-          name: @name, source_dir: @bundle_dir, manifest: @manifest, provenance: @provenance, existing: @existing,
-          results: @results, warnings: @warnings, conflicts: @conflicts,
-          force: @force, strict: @strict, upgrade: @upgrade, dry_run: @dry_run, dev: @dev
-        ).run
-
-        # Files the previous version shipped and this one doesn't.
-        prune_dropped_files(@existing.files, @bundle_md, @target_dir, @target_scope, @provenance) if @upgrade && @existing
+        installed = replace_files
         verify_memory_checksums if @manifest && @strict
         warn_missing_needs(@manifest) if @manifest
         if @manifest && !@dry_run
@@ -113,6 +116,7 @@ module Samagotchi
 
         [@bundle_dir, @manifest]
       ensure
+        note_merges
         # An owned source (git/zip/tar) is cleaned up here, unless an upgrade
         # kept conflicts: the agent step still needs the incoming files, so
         # the caller runs #cleanup_source! when it is done.
@@ -131,9 +135,10 @@ module Samagotchi
         lines << "Source changes: #{@source_change.join(" → ")}" if @source_change
         installed = @results.select { |_, r| r[:status].to_s == "installed" }.keys
         updated = @results.select { |_, r| r[:status].to_s == "updated" }.keys
-        kept = @results.select { |_, r| %w[kept kept_pruned].include?(r[:status].to_s) }.keys
+        merged = merged_files
+        would_merge = @results.select { |_, r| r[:status].to_s == "would_merge" }.keys
+        kept = @results.select { |_, r| %w[kept keep kept_pruned].include?(r[:status].to_s) }.keys
         skipped = @results.select { |_, r| %w[skipped noop would_skip].include?(r[:status].to_s) }.keys
-        conflicts = @results.select { |_, r| r[:status].to_s == "conflict" }.keys
         would_install = @results.select { |_, r| r[:status].to_s == "would_install" }.keys
         fast_forward = @results.select { |_, r| r[:status].to_s == "fast_forward" }.keys
         removed = @results.select { |_, r| r[:status].to_s == "removed" }.keys
@@ -143,11 +148,13 @@ module Samagotchi
         lines << "Updated: #{updated.join(", ")}" unless updated.empty?
         lines << "Would install: #{would_install.join(", ")}" unless would_install.empty?
         lines << "Fast-forward: #{fast_forward.join(", ")}" unless fast_forward.empty?
+        lines << FileStanding.merged_line(merged, @manifest&.version) unless merged.empty?
+        lines << FileStanding.merged_line(would_merge, @manifest&.version, dry_run: true) unless would_merge.empty?
         lines << "Removed (no longer in the bundle): #{removed.join(", ")}#{" (moved to #{trash_dir})" if trash_dir}" unless removed.empty?
         lines << "Would remove (no longer in the bundle): #{would_remove.join(", ")}" unless would_remove.empty?
         lines << "Kept (local edits preserved): #{kept.join(", ")}" unless kept.empty?
         lines << "Skipped: #{skipped.join(", ")}" unless skipped.empty?
-        lines << "Conflicts: #{conflicts.join(", ")}" unless conflicts.empty?
+        lines << trash_copy_line if trash_copy_line
         lines.concat(@warnings) unless @warnings.empty?
         lines.concat(@placeholder_warnings) unless @placeholder_warnings.empty?
         lines << "#{@name} is already installed; `chi bundle upgrade #{@name}` updates it and keeps local edits" if @reinstall
@@ -157,6 +164,28 @@ module Samagotchi
 
       private
 
+      # The steps that replace files: memories, the bundle's own folder, then
+      # the files it dropped. The record isn't written yet, so a failed run is
+      # retried as the same upgrade.
+      # @return [AssetInstaller::Installed]
+      # @raise [InstallError] a file system error (a file it can't read, a
+      #   .trash it can't write)
+      def replace_files
+        install_memories
+
+        installed = AssetInstaller.new(
+          name: @name, source_dir: @bundle_dir, manifest: @manifest, provenance: @provenance, existing: @existing,
+          results: @results, warnings: @warnings, conflicts: @conflicts, trash: @trash,
+          force: @force, strict: @strict, upgrade: @upgrade, dry_run: @dry_run, dev: @dev
+        ).run
+
+        # Files the previous version shipped and this one doesn't.
+        prune_dropped_files(@existing.files, @bundle_md, @target_dir, @target_scope, @provenance) if @upgrade && @existing
+        installed
+      rescue SystemCallError => e
+        raise InstallError, Trash.failure_message(e)
+      end
+
       # Who may install under this name (a manifest can take any name: a
       # repo calling itself guardrails). Sources compare by SourceIdentity
       # (a shipped dir by name, in any gem or checkout; a git URL without
@@ -314,8 +343,12 @@ module Samagotchi
             @owned << file_key if owned_before.include?(file_key)
             skip_existing(file_key, file_path, target_path, @target_scope, owned: owned_before.include?(file_key))
           else
+            # Only --force gets here with a file in place: a copy keeps it.
+            @replaced << file_key if File.exist?(target_path)
+            @trash.copy(target_path) if File.exist?(target_path) && !FileUtils.identical?(file_path, target_path)
             FileUtils.cp(file_path, target_path)
             @owned << file_key
+            @outcomes[file_key] = Merger::INSTALL
             @results[file_key] = { status: "installed" }
             update_target_index(@target_scope, target_path, file_key)
           end
@@ -338,30 +371,71 @@ module Samagotchi
         MemoryFiles.symlinks(@bundle_dir, @manifest).each { |name| @warnings << "#{name} is a symlink (not installed)" }
       end
 
-      # An upgrade's 3-way merge of one file (Merger.classify against the
-      # base the last install recorded); a conflict leaves the local file
-      # and is recorded in @conflicts for the agent step.
+      # An upgrade's 3-way merge of one file (Merger::Upgrade against the
+      # base the last install recorded); a clean text merge replaces the file;
+      # a conflict leaves it and is recorded in @conflicts for the agent step.
       def merge_memory(file_key, file_path, target_path)
-        base_path = @provenance.base_path(file_key)
-        case Merger.classify(base_path: base_path, current_path: target_path, incoming_path: file_path)
+        outcome = @outcomes[file_key] = upgrade_view.outcome(file_key)
+        case outcome.status
         when :install
           FileUtils.cp(file_path, target_path)
           @results[file_key] = { status: "installed" }
         when :fast_forward
+          save_marked_file(file_key, target_path)
           FileUtils.cp(file_path, target_path)
           @results[file_key] = { status: "updated", reason: "auto-merged (not edited)" }
         when :keep
-          @results[file_key] = { status: "kept", reason: "bundle unchanged, local edits preserved" }
+          @results[file_key] = { status: "kept", reason: outcome == Merger::KEEP ? "bundle unchanged, local edits preserved" : "local edits already hold the bundle's changes" }
         when :noop
           @results[file_key] = { status: "skipped", reason: "already up to date" }
+        when :merged
+          if Merger.write_merged(target_path, outcome, @trash)
+            @results[file_key] = { status: "merged", reason: "the bundle's changes joined to local edits" }
+          else
+            note_conflict(file_key, @outcomes[file_key] = Merger::CONFLICT.with(merge: TextMerge.failed(TextMerge::RACED)))
+          end
         when :conflict
-          @results[file_key] = { status: "conflict", reason: "local edits conflict with bundle update" }
-          @conflicts[file_key] = { base: base_path, current: target_path, incoming: file_path }
-          @warnings << "Conflict in #{file_key}: local edits conflict with bundle update (use --force to overwrite or resolve interactively)"
+          note_conflict(file_key, outcome)
+        else raise ArgumentError, "unknown outcome status #{outcome.status.inspect} for #{file_key}" # the base would move with nothing written
         end
         update_target_index(@target_scope, target_path, file_key)
       end
 
+      # The file stays as it is, with the old base and the mark, in FileStanding's
+      # words.
+      def note_conflict(file_key, outcome)
+        behind = upgrade_view.behind(file_key, outcome, @manifest&.version)
+        @behind << behind
+        @results[file_key] = { status: "conflict", reason: behind.state(dry_run: @dry_run) }
+        @conflicts[file_key] = upgrade_view.paths(file_key)
+        @warnings << "#{behind.line(dry_run: @dry_run)} (#{FileStanding::FORCE_TAKES})"
+      end
+
+      # What merged, on the record, a run that failed later too: the file holds the
+      # merge whichever way the run ended. Never fails the run.
+      def note_merges
+        return if merged_files.empty?
+
+        @provenance.note_merged(merged_files, version: @manifest&.version, trash: trash_dir)
+      rescue StandardError => e
+        @warnings << "merge not noted on the record (#{e.message})"
+      end
+
+      def upgrade_view
+        @upgrade_view ||= Merger::Upgrade.new(provenance: @provenance, target_dir: @target_dir, source_dir: @bundle_dir)
+      end
+
+      # A marked file that equals its base, and the update goes ahead: the base
+      # is known to be real (this chi's mark, or ShippedHistory), or no line of the
+      # file goes. A copy is kept, and it says so. (Merger::Upgrade#outcome stops
+      # an older chi's mark otherwise.)
+      def save_marked_file(file_key, target_path)
+        return unless @existing.files.dig(file_key, :conflict)
+
+        @trash.copy(target_path)
+        @warnings << "#{file_key} was marked as kept but matched its recorded base, so it took the update; your copy is in the trash"
+      end
+
       # A dry run's verdict for one file, nothing written: an upgrade
       # classifies as merge_memory would (its status is the classification).
       def preview_memory(file_key, file_path, target_path)
@@ -371,10 +445,10 @@ module Samagotchi
         end
 
         if @upgrade && @existing
-          base_path = @provenance.base_path(file_key)
-          classification = Merger.classify(base_path: base_path, current_path: target_path, incoming_path: file_path)
-          @results[file_key] = { status: classification.to_s }
-          @conflicts[file_key] = { base: base_path, current: target_path, incoming: file_path } if classification == :conflict
+          outcome = upgrade_view.outcome(file_key)
+          return note_conflict(file_key, outcome) if outcome.conflict?
+
+          @results[file_key] = { status: outcome.merged? ? "would_merge" : outcome.status.to_s }
         elsif FileUtils.identical?(file_path, target_path)
           @results[file_key] = { status: "skipped", reason: "already up to date" }
         else
@@ -383,14 +457,15 @@ module Samagotchi
       end
 
       # Strict mode: a memory written from the bundle whose sha256 differs
-      # from its manifest's warns. One that wasn't copied (kept, skipped:
-      # a local edit isn't a bad download) or was merged isn't checked.
+      # from its manifest's warns. One that wasn't copied (kept, skipped, a
+      # dry run's keep and would_skip: a local edit isn't a bad download) or
+      # was merged (merged, a dry run's would_merge) isn't checked.
       def verify_memory_checksums
         @bundle_md.each do |file_key|
           next if @conflicts.key?(file_key)
 
           status = @results[file_key] ? @results[file_key][:status].to_s : nil
-          next if %w[kept kept_pruned fast_forward updated skipped].include?(status)
+          next if %w[kept keep kept_pruned fast_forward updated skipped would_skip merged would_merge].include?(status)
 
           target_path = File.join(@target_dir, file_key)
           next unless File.exist?(target_path)
@@ -437,7 +512,8 @@ module Samagotchi
           plugin_file: installed.plugin_file,
           requires_chi: @manifest.requires_chi,
           needs: @manifest.needs,
-          conflicts: @conflicts.keys,
+          marks: @behind + held_conflict_marks,
+          incoming_dir: @bundle_dir,
           scripts_files: installed.script_files,
           context_providers: @manifest.context_providers,
           file_descriptions: @manifest.file_descriptions,
@@ -447,34 +523,69 @@ module Samagotchi
           setting_types: @manifest.setting_types,
           dev: @dev
         )
+        # Replaced by --force: an earlier merge into it no longer says anything true.
+        @provenance.clear_merge_notes([], files: @replaced)
+      end
+
+      # The files a plain install skipped that are still marked conflict:
+      # Provenance#write rebuilds their entries, and a file it left alone has
+      # missed the bundle's change as much as before (its version may move on
+      # all the same). One with the incoming bytes has nothing left to miss.
+      # @return [Array<FileStanding::Behind>]
+      def held_conflict_marks
+        return [] if @upgrade || @existing.nil?
+
+        kept = @owned.select { |key| @results.dig(key, :reason) == "already exists" && @existing.files.dig(key, :conflict) }
+        kept.map { |key| held_mark(key) }
       end
 
-      # file key => the file whose content becomes its base. A file the
-      # upgrade left as the user has it (kept, noop, conflict, kept_pruned)
-      # keeps its old base, so the next upgrade still sees the local edit;
-      # the rest (installed, updated, skipped) take what is on disk now. A
-      # file the bundle dropped but the user kept stays recorded too.
+      # The mark now speaks of this source's text, so what it says comes from that
+      # text too: what was missed recomputed, an old reason dropped. No merge ran,
+      # so one from an older chi, which can't name sections, keeps its own words.
+      def held_mark(key)
+        entry = @existing.files.fetch(key)
+        return @existing.behind_entry(key, entry).with(version: @manifest.version) if InstalledBundle.legacy_mark?(entry)
+
+        upgrade_view.behind(key, Merger::CONFLICT, @manifest.version)
+      rescue SystemCallError
+        FileStanding::Behind.new(file: key, version: @manifest.version)
+      end
+
+      # file key => the file whose content becomes its base: the one its
+      # Merger::Outcome names (next_base). A file the bundle dropped but the
+      # user kept stays recorded too, with the base it has.
       def upgrade_provenance_files
         files = {}
         @owned.each do |file_key|
-          target_path = File.join(@target_dir, file_key)
-          next unless File.exist?(target_path)
+          next unless File.exist?(File.join(@target_dir, file_key))
 
-          status = @results[file_key] ? @results[file_key][:status].to_s : nil
-          base_path = @provenance.base_path(file_key)
-          files[file_key] = %w[kept noop conflict kept_pruned].include?(status) && File.exist?(base_path) ? base_path : target_path
+          files[file_key] = next_base(file_key, @outcomes.fetch(file_key))
         end
         @existing.files.each_key do |old_key_str|
           next if @bundle_md.include?(old_key_str)
           next unless @results[old_key_str] && @results[old_key_str][:status].to_s == "kept_pruned"
 
-          base_path = @provenance.base_path(old_key_str)
-          src = File.exist?(base_path) ? base_path : File.join(@target_dir, old_key_str)
-          files[old_key_str] = src if File.exist?(src)
+          files[old_key_str] = recorded_base(@provenance.base_path(old_key_str))
         end
         files
       end
 
+      # The file an Outcome's base names. nil for a kept file with no base:
+      # the user's file must not become one, or the next upgrade fast-forwards
+      # over it.
+      def next_base(file_key, outcome)
+        case outcome.base
+        when :recorded then recorded_base(@provenance.base_path(file_key))
+        when :on_disk then File.join(@target_dir, file_key)
+        when :incoming then File.join(@bundle_dir, file_key)
+        else raise ArgumentError, "unknown base #{outcome.base.inspect} for #{file_key}" # nil would drop the base silently
+        end
+      end
+
+      # +base_path+, nil when there is no base (Provenance#write's "keep the
+      # entry, without one").
+      def recorded_base(base_path) = File.exist?(base_path) ? base_path : nil
+
       # file key => its base's content source for a plain install. Skipped
       # for a local edit: keep the installed base, so the next upgrade still
       # sees the edit (not a fast-forward over it).
@@ -483,9 +594,8 @@ module Samagotchi
           target_path = File.join(@target_dir, file_key)
           next unless File.exist?(target_path)
 
-          base_path = @provenance.base_path(file_key)
-          kept = @existing && @results.dig(file_key, :reason) == "already exists" && File.exist?(base_path)
-          map[file_key] = kept ? base_path : target_path
+          kept = @existing && @results.dig(file_key, :reason) == "already exists"
+          map[file_key] = kept ? recorded_base(@provenance.base_path(file_key)) : target_path
         end
         files.merge(dropped_owned_files)
       end
@@ -503,8 +613,7 @@ module Samagotchi
           next if @bundle_md.include?(file_key)
           next unless File.exist?(File.join(@target_dir, file_key))
 
-          base_path = @provenance.base_path(file_key)
-          files[file_key] = base_path if File.exist?(base_path)
+          files[file_key] = recorded_base(@provenance.base_path(file_key))
         end
       end
 
@@ -520,7 +629,7 @@ module Samagotchi
           return
         else
           @results[file_key] = { status: "skipped", reason: "already exists" }
-          @warnings << "Skipped #{file_key} (already exists; use --force to overwrite)"
+          @warnings << "Skipped #{file_key} (already exists; #{FileStanding::FORCE_TAKES})"
         end
         update_target_index(scope, target_path, file_key, owned: owned) unless @dry_run
       end
@@ -548,7 +657,7 @@ module Samagotchi
             remove_target_index(scope, key)
           else
             @results[key] = { status: "kept_pruned", reason: "local edits preserved" }
-            @warnings << "Kept #{key}: no longer in the bundle but edited locally (use --force to remove)"
+            @warnings << "Kept #{key}: no longer in the bundle but edited locally (#{FileStanding::FORCE_MOVES})"
           end
         end
       end

data/lib/samagotchi/memory_bundle/listing.rb

@@ -15,8 +15,9 @@ module Samagotchi
     # its own line, and they aren't listed again.
     module Listing
       # error is set (and the rest nil) when the provenance manifest.json
-      # can't be read; includes is a profile's recorded members, else nil.
-      Installed = Struct.new(:name, :version, :scope, :files, :installed_at, :upgrade, :error, :includes, keyword_init: true)
+      # can't be read; includes is a profile's recorded members, else nil;
+      # behind is its files that stay behind (InstalledBundle#behind_files).
+      Installed = Struct.new(:name, :version, :scope, :files, :installed_at, :upgrade, :error, :includes, :behind, keyword_init: true)
       # source is the name `chi bundle install` takes (the shipped dir's
       # name); includes is a profile's members ([] for a plain bundle).
       Shipped = Struct.new(:name, :source, :version, :description, :includes, keyword_init: true)
@@ -50,7 +51,7 @@ module Samagotchi
           Installed.new(name: name, version: bundle.version, scope: bundle.scope,
                         files: bundle.files.size, installed_at: bundle.installed_at,
                         upgrade: ship && newer?(ship.version, bundle.version) ? ship : nil,
-                        includes: bundle.includes)
+                        includes: bundle.includes, behind: bundle.behind_files)
         end
       end