easy_sync 0.0.5 → 2.0.0

data/lib/easy_sync/jbod/mirror.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+
+module EasySync
+  module Jbod
+    # Mirrors one source folder onto one destination folder with rsync.
+    #
+    # Nothing is ever deleted by rsync itself. Each folder gets two passes: a
+    # read-only check (`rsync -n --delete --itemize-changes --stats`, see
+    # #check) run before any copying starts, then a copy pass with no deletion
+    # flags at all. The check's "*deleting path" lines say which files on the
+    # drive no longer exist on the source (they feed the grace-period purge in
+    # Runner), and its ">f" lines say which existing files the copy would
+    # overwrite (the tripwire, docs/tripwire.md). (`--delete --max-delete=0`
+    # looked like a one-pass alternative, but rsync then only prints
+    # "N skipped" without naming the files, and exits 25.)
+    class Mirror
+      MIN_VERSION = [3, 0, 0].freeze
+      # Anchored to the transfer root, directories only: a share's root-files
+      # unit copies its loose top-level files and nothing below them.
+      ROOT_ONLY = '--exclude=/*/'
+
+      Result = Struct.new(:exit_status, :bytes_transferred, :total_size_bytes, :disk_full, :output,
+                          keyword_init: true) do
+        def success? = exit_status.zero?
+        def disk_full? = !!disk_full
+      end
+
+      # What the read-only check found for one folder. +replaced+ are existing
+      # files on the drive the copy would overwrite; +missing+ is
+      # [[path, kind], ...] on the drive but gone from the source (for the
+      # purge); +junk+ are the missing paths that only match exclude_folders
+      # (already-copied junk, not something lost on the NAS); +new_files+ is
+      # how many files the copy would add; +source_files+ is the source's
+      # regular-file count from --stats. +known+ are paths an earlier run
+      # already found missing (Runner fills it in from pending_deletions):
+      # they wait out the grace period on the drive and are not news, so an
+      # accepted bulk delete doesn't trip again on every run until it's purged.
+      Check = Struct.new(:replaced, :missing, :junk, :new_files, :source_files, :known, keyword_init: true) do
+        def missing_files
+          skip = Set.new(junk) + Array(known)
+          missing.select { |path, kind| kind == 'file' && !skip.include?(path) }.map(&:first)
+        end
+
+        def changed = replaced.size + missing_files.size
+
+        # Files on the drive, worked out without walking it: what the source
+        # has, minus what the copy would add, plus what only the drive has.
+        def files_on_drive = [source_files.to_i - new_files + missing.count { |_, kind| kind == 'file' }, 0].max
+        def samples(limit = 10) = (replaced + missing_files).first(limit)
+      end
+
+      # +excludes+ are rsync patterns (no slash, so they match at any depth):
+      # the config's exclude_folders. They apply to both passes.
+      def initialize(shell: Shell.new, extra_args: [], excludes: [])
+        @shell = shell
+        @extra_args = Array(extra_args)
+        @patterns = Array(excludes)
+        @excludes = @patterns.map { |e| "--exclude=#{e}" }
+      end
+
+      # The copy pass. Extra args (from config, or --dry-run) apply here.
+      # --partial keeps a killed transfer's in-progress file instead of deleting
+      # it, so a multi-GB file interrupted mid-copy resumes next run instead of
+      # restarting from zero.
+      def command(source, destination, root_only: false)
+        argv = ['rsync', '-a', '--partial', '--stats', '--info=progress2', '--itemize-changes', *@excludes]
+        argv << ROOT_ONLY if root_only
+        argv += @extra_args
+        argv + [with_slash(source), with_slash(destination)]
+      end
+
+      # The check probe: never copies, never deletes, only reports.
+      # --stats adds the source's file count, for the tripwire's ratio.
+      # --delete-excluded makes it also report excluded junk that an earlier
+      # run copied before the exclusion existed, so the purge clears it.
+      # A root-files unit (root_only) drops --delete-excluded: its subfolders
+      # are excluded, and they belong to other folders, so they must never be
+      # reported as extraneous. Without --delete-excluded rsync protects them.
+      def probe_command(source, destination, root_only: false)
+        return ['rsync', '-an', '--itemize-changes', '--stats', '--delete', *@excludes, ROOT_ONLY,
+                with_slash(source), with_slash(destination)] if root_only
+
+        ['rsync', '-an', '--itemize-changes', '--stats', '--delete', '--delete-excluded', *@excludes,
+         with_slash(source), with_slash(destination)]
+      end
+
+      # Raises unless the rsync on PATH is new enough for --itemize-changes deletion reporting.
+      def self.check_version!(shell)
+        result = shell.capture(['rsync', '--version'])
+        version = result.output[/rsync\s+version\s+(\d+)\.(\d+)\.(\d+)/, 0]
+        raise Error, 'rsync not found on PATH' unless result.success? && version
+
+        numbers = version.scan(/\d+/).map(&:to_i)
+        return numbers.join('.') if (numbers <=> MIN_VERSION) >= 0
+
+        raise Error, "rsync #{numbers.join('.')} is too old; 3.0 or newer is required (brew install rsync)"
+      rescue Errno::ENOENT
+        raise Error, 'rsync not found on PATH'
+      end
+
+      def sync(source, destination, root_only: false)
+        raise Error, "source folder #{source} does not exist" unless Dir.exist?(source)
+
+        FileUtils.mkdir_p(File.dirname(destination))
+        result = @shell.run(command(source, destination, root_only: root_only))
+        stats = self.class.parse_stats(result.output)
+        Result.new(exit_status: result.status, output: result.output,
+                   disk_full: self.class.disk_full?(result.output), **stats)
+      end
+
+      # Runs the check probe. Returns a Check, or nil if the probe failed (the
+      # caller then neither copies the folder nor records anything for it).
+      def check(source, destination, root_only: false)
+        result = @shell.capture(probe_command(source, destination, root_only: root_only))
+        return nil unless result.success?
+
+        missing = self.class.parse_extraneous(result.output)
+        changes = self.class.parse_file_changes(result.output)
+        Check.new(replaced: changes[:replaced], missing: missing, new_files: changes[:new],
+                  junk: missing.map(&:first).select { |path| junk?(path) },
+                  source_files: self.class.regular_files(result.output))
+      end
+
+      # Re-copies files `scrub` flagged as corrupt/unreadable, overwriting the
+      # bad copy on the drive. `-I` ignores rsync's quick size/mtime check
+      # (which would otherwise skip a file whose size and mtime never
+      # changed - the whole reason rot goes unnoticed). No --partial: an
+      # interrupted refetch must leave the old, still-flagged file in place,
+      # not a half-written one - rsync only renames its temp file over the
+      # target once that file's transfer completes.
+      def refetch(source, destination, relative_paths)
+        list = Tempfile.new('easy_sync-refetch')
+        begin
+          list.write(relative_paths.join("\0"))
+          list.close
+          @shell.run(['rsync', '-a', '-I', '--stats', '--from0', "--files-from=#{list.path}",
+                      with_slash(source), with_slash(destination)])
+        ensure
+          list.unlink
+        end
+      end
+
+      # True when rsync's own output says the destination ran out of space.
+      # Deliberately a text match rather than a specific exit status: rsync
+      # reports this the same way (exit 11) as other unrelated I/O errors.
+      def self.disk_full?(output)
+        output.match?(/No space left on device/i)
+      end
+
+      # Pulls the two numbers we keep out of `rsync --stats` output.
+      def self.parse_stats(output)
+        {
+          total_size_bytes: stat(output, 'Total file size'),
+          bytes_transferred: stat(output, 'Total transferred file size')
+        }
+      end
+
+      # "*deleting   some/dir/" and "*deleting   some/file" lines -> [[path, kind], ...]
+      def self.parse_extraneous(output)
+        output.scan(/^\*deleting\s+(.+?)\r?$/).map do |(path)|
+          path.end_with?('/') ? [path.chomp('/'), 'dir'] : [path, 'file']
+        end
+      end
+
+      # ">f+++++++++ path" is a new file; any other ">f" line is an existing
+      # file the copy would overwrite. Directories, symlinks and
+      # attribute-only (".f") lines change no file's content.
+      def self.parse_file_changes(output)
+        changes = { replaced: [], new: 0 }
+        output.scan(/^>f(\S+) (.+?)\r?$/) do |flags, path|
+          flags.start_with?('+') ? changes[:new] += 1 : changes[:replaced] << path
+        end
+        changes
+      end
+
+      # "Number of files: 1,234 (reg: 1,000, dir: 234)" -> 1000. A source
+      # with no regular files leaves "reg:" out entirely.
+      def self.regular_files(output)
+        line = output[/^Number of files:.*$/] or return 0
+        line[/reg:\s*([\d,]+)/, 1].to_s.delete(',').to_i
+      end
+
+      def self.stat(output, label)
+        match = output[/^#{Regexp.escape(label)}:\s*([\d,.]+)/, 1]
+        match && match.delete(',').to_i
+      end
+
+      private
+
+      # A path the probe reports only because --delete-excluded finds
+      # already-copied junk: one of its components matches exclude_folders.
+      def junk?(path)
+        path.split('/').any? { |part| @patterns.any? { |pat| File.fnmatch?(pat, part) } }
+      end
+
+      def with_slash(path)
+        path.end_with?('/') ? path : "#{path}/"
+      end
+    end
+  end
+end

data/lib/easy_sync/jbod/models.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module EasySync
+  module Jbod
+    Drive = Struct.new(:serial_number, :friendly_name, :capacity_bytes, :added_date, :volume_uuid, :model,
+                       :last_seen_at, :last_used_bytes, :last_free_bytes,
+                       :smart_status, :smart_detail, :smart_checked_at, :power_on_hours, :retired_at,
+                       keyword_init: true) do
+      def retired? = !retired_at.nil?
+
+      def used_fraction
+        return nil if last_used_bytes.nil? || capacity_bytes.to_i.zero?
+
+        last_used_bytes.to_f / capacity_bytes
+      end
+
+      # smartctl's Device Model has no separate "vendor" field for ATA/NVMe
+      # drives (that's a SCSI/USB-bridge thing); the maker is only ever
+      # visible as a token baked into the model string itself, or - for
+      # Seagate - not spelled out at all, just implied by the "ST" model
+      # prefix every Seagate drive uses.
+      BRANDS = {
+        'WDC' => 'Western Digital', 'WD' => 'Western Digital', 'TOSHIBA' => 'Toshiba', 'HGST' => 'HGST',
+        'SAMSUNG' => 'Samsung', 'HITACHI' => 'Hitachi', 'APPLE' => 'Apple', 'SEAGATE' => 'Seagate',
+        'CRUCIAL' => 'Crucial', 'KINGSTON' => 'Kingston', 'INTEL' => 'Intel'
+      }.freeze
+
+      def manufacturer
+        return nil unless model
+
+        token = model[/\A[A-Za-z]+/]
+        return BRANDS[token.upcase] if token && BRANDS.key?(token.upcase)
+
+        'Seagate' if model.match?(/\AST\d/i)
+      end
+
+      # model, with the manufacturer spelled out plainly instead of a raw
+      # token (or, for Seagate, added - its model numbers don't carry one).
+      def branded_model
+        return nil unless model
+        return model unless manufacturer
+
+        rest = model.sub(/\A(?:WDC|WD|TOSHIBA|HGST|SAMSUNG|HITACHI|APPLE|SEAGATE|CRUCIAL|KINGSTON|INTEL)[\s-]+/i, '')
+        "#{manufacturer} #{rest}"
+      end
+
+      # SMART's Power_On_Hours counts only time actually spinning/powered,
+      # unlike calendar age: a 5-year-old drive that sat on a shelf can show
+      # a fraction of the wear of one bought last year and run constantly.
+      def power_on_label
+        return nil unless power_on_hours
+
+        years = power_on_hours / 24.0 / 365
+        return format('%d days (%d hrs)', (power_on_hours / 24.0).round, power_on_hours) if years < 1
+
+        format('%.1f yrs (%d hrs)', years, power_on_hours)
+      end
+    end
+
+    # scope 'tree' is a folder copied with everything under it. scope 'root'
+    # is a share's loose top-level files only (folder_path is the share name);
+    # the share's subfolders are their own 'tree' folders, possibly elsewhere.
+    Folder = Struct.new(:folder_path, :drive_serial, :size_bytes, :assigned_at,
+                        :last_synced_at, :last_sync_status, :scope, keyword_init: true) do
+      def root? = scope == 'root'
+      def share = folder_path.split('/').first
+    end
+
+    # One folder held back (or let through with --accept-changes) by the
+    # tripwire in one sync run. +samples+ is a few of its changed paths.
+    TripRecord = Struct.new(:id, :run_started_at, :folder_path, :scope, :replaced, :missing, :files_on_drive,
+                            :samples, :accepted_at, keyword_init: true) do
+      def changed = replaced.to_i + missing.to_i
+      def accepted? = !accepted_at.nil?
+    end
+
+    HistoryEntry = Struct.new(:id, :folder_path, :drive_serial, :event, :recorded_at, :note,
+                              keyword_init: true)
+
+    SyncRun = Struct.new(:id, :folder_path, :drive_serial, :started_at, :finished_at, :exit_status,
+                         :bytes_transferred, :total_size_bytes, keyword_init: true)
+
+    # One whole `sync` run, summed over its folders (Manifest#run_summaries).
+    # copied counts folders that transferred any bytes; the rest only
+    # confirmed nothing had changed.
+    RunSummary = Struct.new(:run_started_at, :last_finished_at, :folders, :copied, :bytes_transferred, :failed,
+                            keyword_init: true)
+
+    # A path on a drive that is a candidate for deletion, either because
+    # rsync reported it gone from the NAS (cause 'missing_on_nas';
+    # relative_path is '' with kind 'folder' when the whole folder is gone)
+    # or because the folder was reassigned off +drive_serial+ (cause
+    # 'reassigned', always whole-folder; relative_path there holds the old
+    # drive's serial instead of a real path, only so a second reassignment of
+    # the same folder before the first cleanup runs gets its own row rather
+    # than colliding on the folder_path+relative_path uniqueness).
+    PendingDeletion = Struct.new(:id, :folder_path, :relative_path, :kind, :drive_serial, :cause, :first_missing_at,
+                                 :last_missing_at, :missing_runs, keyword_init: true) do
+      def whole_folder? = kind == 'folder'
+      def reassigned? = cause == 'reassigned'
+
+      def expires_at(grace_days)
+        Time.parse(first_missing_at) + (grace_days * 86_400)
+      end
+
+      def expired?(now:, grace_days:, grace_runs:)
+        missing_runs >= grace_runs && expires_at(grace_days) <= now
+      end
+    end
+
+    Deletion = Struct.new(:id, :folder_path, :relative_path, :kind, :drive_serial, :first_missing_at, :deleted_at,
+                          keyword_init: true)
+
+    # One tracked file on one drive, for `scrub` (see docs/integrity-scan.md).
+    # digest is the SHA-256 baseline (nil until the first hash); status is
+    # 'ok', 'corrupt' (hash mismatch), 'unreadable' (a read error), or
+    # 'unresolved' (still bad after sync refetched it - never refetched
+    # again automatically).
+    FileChecksum = Struct.new(:drive_serial, :folder_path, :relative_path, :size_bytes, :mtime, :digest,
+                              :verified_at, :status, :failed_at, :refetched_at, keyword_init: true) do
+      def ok? = status == 'ok'
+      def flagged? = %w[corrupt unreadable].include?(status)
+      def unresolved? = status == 'unresolved'
+      def refetched? = !refetched_at.nil?
+      def label = "#{folder_path}/#{relative_path}"
+    end
+
+    # One `benchmark` run on one drive (see Jbod::Benchmarker). MB/s is
+    # MiB/s, the same unit scrub reports. used_bytes is how full the drive was
+    # at the time: a fuller drive writes to slower inner tracks, so a gradual
+    # decline that tracks it is expected, not a warning sign.
+    DriveBenchmark = Struct.new(:id, :drive_serial, :run_at, :bytes, :write_mb_s, :read_mb_s, :used_bytes,
+                                keyword_init: true)
+
+    # One row per folder seen on the NAS at the last completed placement
+    # pass: placed (assigned to a drive, synced or queued), unplaced (no drive
+    # has room, or nothing is mounted) or empty (no real files).
+    SourceEntry = Struct.new(:folder_path, :size_bytes, :state, :detail, :seen_at, keyword_init: true) do
+      def share = folder_path.split('/').first
+    end
+
+    # SMART health as last read from the drive. status is one of
+    # 'ok' (self-assessment passed, no bad-sector counters), 'warning' (passed
+    # but reallocated/pending/uncorrectable sectors or an NVMe critical flag:
+    # the drive is starting to fail), 'failing' (self-assessment FAILED), or
+    # 'unknown' (SMART not exposed by the enclosure, smartctl missing, etc.).
+    # reallocated_sector_ct is the raw counter, tracked separately over time
+    # (see Manifest#record_smart_check) so a drive whose count is old and
+    # unchanging can be told apart from one that's actively climbing.
+    # other_bad is true when pending/uncorrectable sectors, media errors, or
+    # an NVMe critical-warning flag also contributed to a 'warning' status -
+    # those are never downgraded by reallocated-count history.
+    Health = Struct.new(:status, :detail, :source, :power_on_hours, :reallocated_sector_ct, :other_bad,
+                        keyword_init: true)
+
+    # A registered drive that is currently mounted, with live usage numbers.
+    MountedDrive = Struct.new(:drive, :mount_point, :capacity_bytes, :used_bytes, :free_bytes,
+                              keyword_init: true) do
+      def serial_number = drive.serial_number
+      def friendly_name = drive.friendly_name
+    end
+  end
+end

data/lib/easy_sync/jbod/page_cache.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'fiddle'
+
+module EasySync
+  module Jbod
+    # Drops one file's pages from the macOS unified buffer cache, so the read
+    # that follows comes off the drive. F_NOCACHE alone is not enough: it
+    # stops a read from *adding* pages to the cache, but pages already there
+    # (a file sync just wrote, or anything read recently) are still served
+    # from RAM. Measured on jbod-test-1 (USB): a just-synced 100 MB file read
+    # at 12,037 MB/s with F_NOCACHE, and at 156 MB/s after this. msync with
+    # MS_INVALIDATE is the BSD/macOS stand-in for Linux's
+    # posix_fadvise(DONTNEED) (vmtouch uses it the same way); MS_SYNC first
+    # flushes any pending writes, so nothing unwritten is ever discarded.
+    # Best effort: any failure just leaves the cache as it was.
+    module PageCache
+      PROT_READ = 0x01
+      MAP_SHARED = 0x01
+      MS_SYNC = 0x10
+      MS_INVALIDATE = 0x02
+
+      module_function
+
+      def evict(io)
+        len = io.size
+        return false if len.zero?
+
+        addr = functions[:mmap].call(nil, len, PROT_READ, MAP_SHARED, io.fileno, 0)
+        return false if [-1, (2**64) - 1].include?(addr.to_i)
+
+        begin
+          functions[:msync].call(addr, len, MS_SYNC | MS_INVALIDATE).zero?
+        ensure
+          functions[:munmap].call(addr, len)
+        end
+      rescue StandardError, Fiddle::DLError
+        false
+      end
+
+      def functions
+        @functions ||= begin
+          libc = Fiddle.dlopen(nil)
+          {
+            mmap: Fiddle::Function.new(libc['mmap'], [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_INT,
+                                                      Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_LONG_LONG],
+                                       Fiddle::TYPE_VOIDP),
+            msync: Fiddle::Function.new(libc['msync'], [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_INT],
+                                        Fiddle::TYPE_INT),
+            munmap: Fiddle::Function.new(libc['munmap'], [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T], Fiddle::TYPE_INT)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/easy_sync/jbod/placement.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module EasySync
+  module Jbod
+    # Decides where a brand-new folder goes. Pure logic, no I/O.
+    #
+    # Rule: a drive in +prefer+ (one already holding part of the same share)
+    # wins if the folder fits there, so a share stays on one drive while it
+    # can; otherwise the mounted drive with the most free space wins. A folder
+    # is never placed on a drive it would not fit on, and existing folders are
+    # never moved (that is what makes the JBOD layout browsable by hand).
+    module Placement
+      class NoMountedDrives < Error; end
+      class DoesNotFit < Error; end
+
+      # +candidates+ are MountedDrive structs. +size_bytes+ is the folder size
+      # (nil when unknown, in which case only the free-space ordering applies).
+      # +reserve_bytes+ is headroom to leave on the drive after placement.
+      def self.choose(candidates, size_bytes: nil, reserve_bytes: 0, prefer: [])
+        raise NoMountedDrives, 'no registered drives are mounted' if candidates.empty?
+
+        preferred = candidates.select do |c|
+          prefer.include?(c.serial_number) && (size_bytes.nil? || c.free_bytes - reserve_bytes >= size_bytes)
+        end
+        pool = preferred.empty? ? candidates : preferred
+        best = pool.max_by { |c| [c.free_bytes, c.friendly_name.to_s] }
+        if size_bytes && (best.free_bytes - reserve_bytes) < size_bytes
+          raise DoesNotFit,
+                "#{format_bytes(size_bytes)} does not fit on #{best.friendly_name} " \
+                "(#{format_bytes(best.free_bytes)} free, #{format_bytes(reserve_bytes)} reserved)"
+        end
+        best
+      end
+
+      # "2gb", "500 MB", 2147483648 -> bytes. Used for config values and CLI flags.
+      def self.parse_size(value)
+        return value.to_i if value.is_a?(Numeric)
+
+        m = value.to_s.strip.match(/\A([\d.]+)\s*(tb|gb|mb|kb|b)?\z/i) or raise Error, "cannot parse size #{value.inspect} (try 2gb)"
+        (m[1].to_f * { nil => 1, 'b' => 1, 'kb' => 1024, 'mb' => 1024**2, 'gb' => 1024**3, 'tb' => 1024**4 }[m[2]&.downcase]).to_i
+      end
+
+      UNITS = %w[B KB MB GB TB PB].freeze
+
+      def self.format_bytes(bytes)
+        return '—' if bytes.nil?
+
+        value = bytes.to_f
+        unit = 0
+        while value >= 1024 && unit < UNITS.size - 1
+          value /= 1024
+          unit += 1
+        end
+        unit.zero? ? "#{bytes} B" : format('%.1f %s', value, UNITS[unit])
+      end
+
+      # "3d 4h", "2h 34m", "45m", or "12s". Shared by `status` and the
+      # dashboard so an elapsed/remaining time reads the same everywhere.
+      def self.format_duration(seconds)
+        days, rem = seconds.to_i.divmod(86_400)
+        hours, rem = rem.divmod(3600)
+        minutes, secs = rem.divmod(60)
+        return "#{days}d #{hours}h" if days.positive?
+        return "#{hours}h #{minutes}m" if hours.positive?
+        return "#{minutes}m #{secs}s" if minutes.positive?
+
+        "#{secs}s"
+      end
+    end
+  end
+end

data/lib/easy_sync/jbod/planner.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module EasySync
+  module Jbod
+    # `easy_sync plan`: measures each configured share and checks that every
+    # top-level folder (each is placed on its own) fits on the largest drive
+    # in the fleet. Reads only; never places or copies anything.
+    class Planner
+      Row = Struct.new(:source, :mounted, :size_bytes, :subfolders, :largest_subfolder, :largest_name, :loose_files,
+                       :reason, :fits, keyword_init: true)
+
+      def initialize(settings, shell: Shell.new, largest_drive_bytes: nil)
+        @settings = settings
+        @shell = shell
+        @largest = largest_drive_bytes
+      end
+
+      # +only+ restricts to sources whose basename or full path is in the list
+      # (e.g. easy_sync plan pro, matching /Volumes/pro). nil measures all.
+      def rows(only: nil)
+        sources = Array(@settings[:sources]).map { |e| Runner::Source.from_config(e) }
+        sources = sources.select { |s| only.include?(s.name) || only.include?(s.path) } if only
+        sources.map { |src| measure(src) }
+      end
+
+      private
+
+      def measure(source)
+        row = Row.new(source: source, mounted: Dir.exist?(source.path) && !Dir.empty?(source.path), loose_files: 0,
+                      subfolders: 0)
+        return row.tap { |r| r.reason = 'not mounted (or empty)' } unless row.mounted
+
+        excluded = Array(@settings[:exclude_folders])
+        children = Dir.children(source.path).sort.reject { |n| excluded.include?(n) || n.start_with?('.') }
+        dirs = children.select { |n| File.directory?(File.join(source.path, n)) }
+        row.loose_files = children.count { |n| File.file?(File.join(source.path, n)) }
+        row.subfolders = dirs.size
+
+        sizes = du(dirs.map { |n| File.join(source.path, n) })
+        row.size_bytes = sizes.values.sum
+        row.largest_name, row.largest_subfolder = sizes.max_by { |_, v| v } || [nil, 0]
+        check_fit(row)
+      end
+
+      # One `du -sk` over every subfolder; the tool's own `du` cost was
+      # measured at ~6 s for 2,380 movie folders over SMB.
+      def du(paths)
+        return {} if paths.empty?
+
+        result = @shell.capture(['du', '-sk', *paths])
+        result.output.each_line.with_object({}) do |line, h|
+          kb, path = line.chomp.split("\t", 2)
+          next unless kb && path
+
+          h[File.basename(path.chomp('/'))] = kb.to_i * 1024
+        end
+      end
+
+      def check_fit(row)
+        largest = @largest
+        if largest.nil?
+          row.reason = 'register a drive (or pass --largest-drive) to check whether every folder fits'
+        elsif row.largest_subfolder.to_i > largest
+          row.fits = false
+          row.reason = "WARNING: #{row.largest_name} alone is #{Placement.format_bytes(row.largest_subfolder)}, " \
+                       "bigger than the largest drive currently registered (#{Placement.format_bytes(largest)}); " \
+                       'it cannot be placed on this fleet today, but will fit once you add a bigger drive'
+        else
+          row.fits = true
+          row.reason = 'every folder fits on the largest drive'
+        end
+        row
+      end
+    end
+  end
+end