metaclean 4.1.0 → 4.2.0

data/lib/metaclean/discovery.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Metaclean
+  class Discovery
+    attr_reader :scan_errors, :guards
+
+    def initialize(recursive: false)
+      @recursive = recursive
+      @scan_errors = 0
+      @guards = {}
+    end
+
+    def expand(paths)
+      @scan_errors = 0
+      @guards = {}
+      explicit = []
+      discovered = []
+      paths.each do |path|
+        collect_path(path, explicit, discovered)
+      end
+      discovered.reject! { |file| skip?(file) }
+      result = dedupe_by_realpath(explicit + discovered)
+      result.select do |file|
+        @guards[file] = FileOps.path_guard!(file)
+        true
+      rescue Error, SystemCallError => e
+        scan_failed(file, e)
+        false
+      end
+    end
+
+    def skip?(file)
+      base = File.basename(file)
+      base.start_with?('.') ||
+        base.end_with?('.bak') ||
+        base.match?(Metaclean::CLEAN_OUTPUT_RE) ||
+        base.include?(Metaclean::TMP_MARKER)
+    end
+
+    def dedupe_by_realpath(paths)
+      seen = {}
+      paths.each_with_object([]) do |path, result|
+        key = safe_realpath(path)
+        next if seen[key]
+
+        seen[key] = true
+        result << path
+      end
+    end
+
+    private
+
+    def collect_path(path, explicit, discovered)
+      unless File.exist?(path) || File.symlink?(path)
+        Display.warning "Not found: #{path}"
+        @scan_errors += 1
+        return
+      end
+
+      FileOps.path_guard!(path)
+      if File.directory?(path)
+        collect_dir(path, discovered)
+      elsif File.file?(path)
+        explicit << path
+      else
+        scan_failed(path, Error.new('not a regular file or directory'))
+      end
+    rescue Error, SystemCallError => e
+      scan_failed(path, e)
+    end
+
+    def safe_realpath(path)
+      File.realpath(path)
+    rescue SystemCallError
+      path
+    end
+
+    def collect_dir(dir, files)
+      if @recursive
+        walk_recursive(dir, files)
+      else
+        Dir.children(dir).each do |entry|
+          next if entry.start_with?('.')
+
+          path = File.join(dir, entry)
+          next if File.symlink?(path)
+
+          begin
+            FileOps.path_guard!(path)
+            files << path if File.file?(path)
+          rescue Error, SystemCallError => e
+            scan_failed(path, e)
+          end
+        end
+      end
+    rescue SystemCallError => e
+      scan_failed(dir, e)
+    end
+
+    def walk_recursive(dir, files)
+      Dir.each_child(dir) do |entry|
+        next if entry.start_with?('.')
+
+        path = File.join(dir, entry)
+        next if File.symlink?(path)
+
+        begin
+          FileOps.path_guard!(path)
+          if File.directory?(path)
+            walk_recursive(path, files)
+          elsif File.file?(path)
+            files << path
+          end
+        rescue Error, SystemCallError => e
+          scan_failed(path, e)
+        end
+      end
+    rescue SystemCallError => e
+      scan_failed(dir, e)
+    end
+
+    def scan_failed(dir, error)
+      Display.warning "Skipping #{dir}: #{error.message}"
+      @scan_errors += 1
+    end
+  end
+end

data/lib/metaclean/display.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-# All terminal output lives here: ANSI colors, headers, tables, the
-# before/after diff. Colors are gated on `tty?` (see color?).
-
 module Metaclean
   module Display
     COLORS = {
@@ -17,14 +14,8 @@ module Metaclean
       gray:    "\e[90m"
     }.freeze
 
-    # ExifTool reports four "groups" that are descriptions of the file
-    # itself, not embedded metadata: System (filesystem stat), File (header
-    # info), ExifTool (its own version), Composite (computed values).
-    # Excluding these makes the diff focus on what actually got stripped.
     NON_METADATA_GROUPS = %w[System File ExifTool Composite].freeze
 
-    # ASCII wordmark shown at the top of --help / --version. Printed by `banner`
-    # (see there for why it's colored line-by-line).
     LOGO = <<~ART
       ███╗   ███╗███████╗████████╗ █████╗  ██████╗██╗     ███████╗ █████╗ ███╗   ██╗
       ████╗ ████║██╔════╝╚══██╔══╝██╔══██╗██╔════╝██║     ██╔════╝██╔══██╗████╗  ██║
@@ -36,21 +27,28 @@ module Metaclean
 
     module_function
 
-    # Decides whether to emit ANSI color codes. Colors are wrong when:
-    #   * stdout is a pipe/file (not a terminal) — `tty?` is false there
-    #   * NO_COLOR env var is set (de-facto convention, see no-color.org)
+    def configure(quiet: false, redact_values: false)
+      @quiet = quiet
+      @redact_values = redact_values
+    end
+
+    def quiet?
+      @quiet == true
+    end
+
+    def redact_values?
+      @redact_values == true
+    end
+
     def color?
       return @color if defined?(@color)
 
-      # Per https://no-color.org: disable only when NO_COLOR is set to a
-      # non-empty value. An unset or empty NO_COLOR leaves colors on.
       no_color = ENV['NO_COLOR'].to_s
       @color = $stdout.tty? && no_color.empty?
       @color = true if ENV['FORCE_COLOR']
       @color
     end
 
-    # Wrap text in a color, or pass it through plain when colors are off.
     def c(text, color)
       text = printable(text)
       return text unless color?
@@ -58,35 +56,30 @@ module Metaclean
       "#{COLORS[color]}#{text}#{COLORS[:reset]}"
     end
 
-    # Red ASCII wordmark (matches Ruby's brand color) + one-line tagline for
-    # --help / --version. Colored line-by-line on purpose: `c` runs text through
-    # `printable`, which turns control chars (including the heredoc's newlines)
-    # into spaces — so coloring the whole block at once would collapse the logo
-    # onto one line.
     def banner
       LOGO.each_line { |line| puts c(line.chomp, :red) }
       puts c('  strip EXIF · IPTC · XMP · GPS · ID3 — leave the file clean', :gray)
     end
 
     def header(text)
+      return if quiet?
+
       puts
       puts c('━' * 64, :gray)
       puts c(text, :bold)
       puts c('━' * 64, :gray)
     end
 
-    def section(text); puts c("▸ #{text}",  :cyan);  end
-    def info(text);    puts c("  #{text}",  :gray);  end
-    def success(text); puts c("✓ #{text}",  :green); end
+    def section(text); puts c("▸ #{text}",  :cyan) unless quiet?;  end
+    def info(text);    puts c("  #{text}",  :gray) unless quiet?;  end
+    def success(text); puts c("✓ #{text}",  :green) unless quiet?; end
     def warning(text); puts c("⚠ #{text}",  :yellow);end
 
-    # `error` returns a string instead of printing it — callers usually want
-    # to send it to STDERR via `warn`, not stdout via `puts`.
     def error(text); c("✗ #{text}", :red); end
 
-    # Prints a metadata Hash as a grouped, indented table.
-    # `only_embedded:` filters out the System/File/etc. noise.
     def metadata_table(meta, only_embedded: false)
+      return if quiet?
+
       rows = meta.reject { |k, _| k == 'SourceFile' }
       rows = rows.select { |k, _| embedded_key?(k) } if only_embedded
 
@@ -95,120 +88,110 @@ module Metaclean
         return
       end
 
-      # Group "GPS:*", "EXIF:*", … each into its own labeled sub-table.
       grouped = rows.group_by { |k, _| group_of(k) }
       grouped.sort_by { |g, _| g.to_s }.each do |group, pairs|
         puts c("  [#{group}]", :magenta)
         pairs.sort_by { |k, _| k.to_s }.each do |k, v|
           tag = k.to_s.split(':', 2).last
-          line = format('    %-38s %s', truncate(tag, 38), truncate(format_value(v), 60))
+          line = format('    %-38s %s', truncate(tag, 38), truncate(visible_value(v), 60))
           puts c(line, :dim)
         end
       end
     end
 
-    # Compares two metadata hashes (before vs after) and prints three
-    # sections: removed, changed, still-present. This is the "before/after"
-    # the user asked for.
     def diff(before, after)
-      keys = (before.keys + after.keys).uniq.select { |k| embedded_key?(k) }
-
-      removed = []
-      changed = []
-      kept    = []
-
-      keys.sort.each do |k|
-        b = before[k]
-        a = after[k]
-        if a.nil? && !b.nil?
-          removed << [k, b]
-        elsif !b.nil? && a != b
-          changed << [k, b, a]
-        elsif !b.nil?
-          kept << [k, b]
-        end
+      return if quiet?
+
+      removed, changed, kept = classify_diff(before, after)
+      render_removed(removed)
+      render_changed(changed)
+      render_kept(kept)
+
+      if [removed, changed, kept].all?(&:empty?)
+        info 'Nothing to strip — file already clean.'
+      elsif removed.empty? && changed.empty?
+        info 'No tags were removed — see "Still present" above.'
       end
+    end
 
-      if removed.any?
-        section "Removed (#{removed.size})"
-        removed.each do |k, b|
-          puts "  #{c('-', :red)} #{c(k, :red)}  #{c(truncate(format_value(b), 60), :gray)}"
+    def classify_diff(before, after)
+      rows = [[], [], []]
+      keys = (before.keys + after.keys).uniq.select { |key| embedded_key?(key) }
+      keys.sort.each do |key|
+        old_value = before[key]
+        new_value = after[key]
+        if new_value.nil? && !old_value.nil?
+          rows[0] << [key, old_value]
+        elsif !old_value.nil? && new_value != old_value
+          rows[1] << [key, old_value, new_value]
+        elsif !old_value.nil?
+          rows[2] << [key, old_value]
         end
       end
+      rows
+    end
 
-      if changed.any?
-        section "Changed (#{changed.size})"
-        changed.each do |k, b, a|
-          puts "  #{c('~', :yellow)} #{c(k, :yellow)}"
-          puts "      #{c('-', :red)}   #{truncate(format_value(b), 60)}"
-          puts "      #{c('+', :green)} #{truncate(format_value(a), 60)}"
-        end
+    def render_removed(rows)
+      return if rows.empty?
+
+      section "Removed (#{rows.size})"
+      rows.each do |key, value|
+        puts "  #{c('-', :red)} #{c(key, :red)}  #{c(truncate(visible_value(value), 60), :gray)}"
       end
+    end
 
-      if kept.any?
-        section "Still present (#{kept.size})"
-        kept.each do |k, b|
-          puts "  #{c('=', :gray)} #{c(k, :gray)}  #{c(truncate(format_value(b), 60), :gray)}"
-        end
+    def render_changed(rows)
+      return if rows.empty?
+
+      section "Changed (#{rows.size})"
+      rows.each do |key, old_value, new_value|
+        puts "  #{c('~', :yellow)} #{c(key, :yellow)}"
+        puts "      #{c('-', :red)}   #{truncate(visible_value(old_value), 60)}"
+        puts "      #{c('+', :green)} #{truncate(visible_value(new_value), 60)}"
       end
+    end
 
-      if removed.empty? && changed.empty? && kept.empty?
-        info 'Nothing to strip — file already clean.'
-      elsif removed.empty? && changed.empty?
-        info 'No tags were removed — see "Still present" above.'
+    def render_kept(rows)
+      return if rows.empty?
+
+      section "Still present (#{rows.size})"
+      rows.each do |key, value|
+        puts "  #{c('=', :gray)} #{c(key, :gray)}  #{c(truncate(visible_value(value), 60), :gray)}"
       end
     end
 
-    # Group name out of "Group:Tag" (split caps at 2 so a ":" in the value is safe).
     def group_of(key)
       key.to_s.split(':', 2).first.to_s
     end
 
-    # True when `key` names real embedded metadata: not the SourceFile
-    # bookkeeping key, and not one of the System/File/ExifTool/Composite
-    # groups that describe the file rather than its embedded tags. Single
-    # source of truth for "is this a tag we actually stripped?" — shared by
-    # the table, diff, count, removed-count and privacy-residual checks.
     def embedded_key?(key)
       key != 'SourceFile' && !NON_METADATA_GROUPS.include?(group_of(key))
     end
 
-    # Make any value safe to print on a single line. Hashes/Arrays get
-    # `inspect` (shows their structure); strings are collapsed to single
-    # spaces so a multiline tag value doesn't wreck the table.
     def format_value(v)
       case v
       when Hash, Array then printable(v.inspect)
       else
-        # Guard the regexp gsub against invalid-encoding tag values — gsub raises
-        # ArgumentError on them. Exiftool.read already scrubs; this is belt-and-
-        # suspenders so the display layer can never crash the run on hostile bytes.
         s = printable(v)
         s.gsub(/\s+/, ' ')
       end
     end
 
-    # Render untrusted filenames/metadata as terminal text, not terminal control.
-    # Exif/Office/PDF metadata can contain ANSI/OSC escape bytes; printing those
-    # raw can recolor output, rewrite a terminal title, or worse. We keep the
-    # content readable by replacing C0/DEL and C1 control chars with spaces
-    # (C1, U+0080–U+009F, holds the 8-bit CSI/OSC introducers some terminals honor).
+    def visible_value(value)
+      redact_values? ? '[redacted]' : format_value(value)
+    end
+
     def printable(text)
       s = text.to_s
       s = s.scrub unless s.valid_encoding?
       s.gsub(/[[:cntrl:]]/, ' ')
     end
 
-    # Truncate to N chars with a single-character ellipsis. We use "…"
-    # (one Unicode char) instead of "..." so the truncation doesn't itself
-    # spill over the budget.
     def truncate(s, n)
       s = s.to_s
       s.length > n ? "#{s[0, n - 1]}…" : s
     end
 
-    # How many "real" embedded tags are there? Used for the
-    # "Before (24 embedded tags) → After (0)" summary line.
     def count_embedded(meta)
       meta.keys.count { |k| embedded_key?(k) }
     end

data/lib/metaclean/exiftool.rb

@@ -1,66 +1,38 @@
 # frozen_string_literal: true
 
-# Thin wrapper around the external `exiftool` binary.
-#
-# Open3.capture3 with multiple args bypasses the shell, so a filename like
-# `cat; rm -rf /` is one argument, not a command. That's not the whole story:
-# exiftool still parses its own arguments, so a filename beginning with "-"
-# (e.g. `-config`) would be read as an option. Every path goes through
-# `Metaclean.safe_path`, which prefixes a leading dash with "./" so it's
-# always seen as a filename.
-
-require 'open3'
 require 'json'
 
 module Metaclean
   module Exiftool
     module_function
 
-    # True if `exiftool` is on PATH. Memoized so repeated checks don't re-spawn
-    # it (defined? not nil? — the cached value can legitimately be false).
     def available?
       return @available if defined?(@available)
 
-      out, _err, status = Open3.capture3('exiftool', '-ver')
+      out, _err, status = Metaclean.capture3(
+        'exiftool', '-ver',
+        timeout: Metaclean::PROBE_TIMEOUT,
+        max_output: Metaclean::PROBE_MAX_OUTPUT_BYTES
+      )
       @available = status.success?
-      # Stash the version off the same call so `version` need not re-spawn.
       @version = @available ? out.strip : nil
       @available
-    rescue Errno::ENOENT
+    rescue Errno::ENOENT, Error
       @version = nil
-      @available = false # exiftool not on PATH
+      @available = false
     end
 
-    # Returns the version string, or nil if exiftool is missing/broken.
-    # Captured by `available?`, so this never re-runs the binary.
     def version
       available? ? @version : nil
     end
 
-    # Reads metadata from a file and returns a flat Hash of "Group:Tag" => value.
-    #
-    # ExifTool flag glossary:
-    #   -j         JSON output (machine-parseable)
-    #   -G1        Include the family-1 group name. NB: with -G1 mainstream EXIF
-    #              tags appear under "IFD0"/"ExifIFD"/"IFD1", not "EXIF" (that's
-    #              the family-0 name); GPS/IPTC/XMP-dc keep those group names.
-    #   -a         Allow duplicate tags (some formats have several with same name)
-    #   -u         Include unknown/unidentified tags
-    #   -s         Short tag names (no descriptions)
-    #   -n         Numeric values (no human formatting like "1/100 sec")
-    #   -api largefilesupport=1   Allow files >4 GB
     def read(path)
       out, err, status = Metaclean.capture3(
         'exiftool', '-j', '-G1', '-a', '-u', '-s', '-n', '-api', 'largefilesupport=1',
         Metaclean.safe_path(path)
       )
-      raise Error, "ExifTool read failed: #{err.strip}" unless status.success?
+      raise Error, "ExifTool read failed: #{read_error_detail(out, err)}" unless status.success?
 
-      # ExifTool's JSON output is an array (one entry per file). We always
-      # pass one file, so we take the first element. `|| {}` handles the
-      # edge case where exiftool returns an empty array. A non-array shape is
-      # unexpected — bail with a clear error instead of crashing later on
-      # `.first` returning a Hash/scalar.
       data = JSON.parse(out)
       raise Error, 'Unexpected ExifTool output (expected a JSON array)' unless data.is_a?(Array)
 
@@ -69,12 +41,17 @@ module Metaclean
       raise Error, "Could not parse ExifTool output: #{e.message}"
     end
 
-    # ExifTool labels its -j output UTF-8, but binary/odd tag values (UserComment,
-    # MakerNotes fragments, corrupt or hostile files) can carry invalid bytes. A
-    # later gsub (Display.format_value) raises on an invalid-encoding String and
-    # would crash the whole run, so replace bad bytes up front. This hash is only
-    # used for display/diff/residual checks — the actual strip operates on the
-    # file via the tools — so scrubbing is safe.
+    def read_error_detail(out, err)
+      return err.strip unless err.strip.empty?
+
+      data = JSON.parse(out)
+      entry = data.is_a?(Array) ? data.first : nil
+      detail = entry && (entry['ExifTool:Error'] || entry['Error'])
+      detail ? detail.to_s.strip : 'unknown error'
+    rescue JSON::ParserError
+      'unknown error'
+    end
+
     def scrub_encoding(obj)
       case obj
       when String then obj.valid_encoding? ? obj : obj.scrub
@@ -84,35 +61,27 @@ module Metaclean
       end
     end
 
-    # ExifTool can READ many formats it cannot WRITE, and mat2 owns the strip for
-    # them: the ZIP-based documents (docx/xlsx/pptx/odt/ods/odp/odg/odf/epub) and
-    # the RIFF containers (avi/wav). ExifTool announces the inability with one of
-    # a few phrasings — "writing of X files is not yet supported", "does not yet
-    # support writing of …", or "Can't currently write RIFF … files" — so we
-    # match all of them. strip! returns :unsupported in these cases so the runner
-    # treats it as a soft skip (mat2 does the actual strip), NOT a pipeline
-    # failure that would wrongly pin an already-clean file at :unverified. This is
-    # safe because the post-strip residual re-read still gates the :cleaned status.
-    WRITE_UNSUPPORTED_RE = /not yet support|can't currently write|writing of .* files/i
-
-    # Removes every removable tag, in place. Returns true on success,
-    # :unsupported when ExifTool cannot write the format, and raises on failure.
-    #
-    # `-all=` sets every tag to empty, which deletes them. `-overwrite_original`
-    # makes ExifTool replace the file directly instead of writing `file_original`
-    # next to it. `-api largefilesupport=1` lets files larger than 4 GB through.
+    WRITE_UNSUPPORTED_RE = /
+      writing\sof\s(?:this\stype\sof\s|[^\s]+\s)?files?\sis\snot\s(?:yet\s)?supported |
+      can't\scurrently\swrite |
+      does\snot\syet\ssupport\swriting
+    /ix
+
+    PRESERVE_TAGS = %w[Orientation ICC_Profile].freeze
+
     def strip!(path, also_delete: [])
-      # `-all=` clears metadata, but for TIFF/DNG ExifTool refuses to delete the
-      # IFD0 directory and leaves its tags (Artist, Software, …) behind. So we
-      # ALSO delete the known privacy tags by name and clear the GPS group: both
-      # are no-ops where `-all=` already removed them (e.g. JPEG), but they make
-      # the strip complete AND lossless (no re-encode) for IFD0-preserving formats.
+      FileOps.regular_stat!(path)
       args = ['exiftool', '-all=', '-gps:all=']
       also_delete.each { |tag| args << "-#{tag}=" }
+      args.concat(['-tagsfromfile', '@'])
+      PRESERVE_TAGS.each { |tag| args << "-#{tag}" }
       args.concat(['-overwrite_original', '-q', '-q', '-api', 'largefilesupport=1', Metaclean.safe_path(path)])
 
       _out, err, status = Metaclean.capture3(*args)
-      return true if status.success?
+      if status.success?
+        FileOps.validate_output!(path)
+        return true
+      end
       return :unsupported if err.match?(WRITE_UNSUPPORTED_RE)
 
       raise Error, "ExifTool strip failed: #{err.strip}"