metaclean 1.0.2 → 4.0.1

data/lib/metaclean/strategy.rb

@@ -1,23 +1,41 @@
 # frozen_string_literal: true
 
-# ───────────────────────────────────────────────────────────────────────────
 # The "policy" module: which tools to run for which file, and what counts as
 # privacy-relevant if it survives a clean.
 #
 # Keeping this logic in its own file means the runner doesn't need to know
 # about formats — it just asks Strategy.tools_for(path) and runs whatever
 # comes back.
-# ───────────────────────────────────────────────────────────────────────────
 
 module Metaclean
   module Strategy
-    # Tag GROUPS that almost always carry personally identifying info.
-    # Survival of any tag in these groups raises a flag to the user.
-    PRIVACY_GROUPS = %w[GPS MakerNotes XMP-dc XMP-photoshop IPTC ICC-header].freeze
+    # Group-name PREFIXES treated as privacy-bearing. Matching whole families by
+    # prefix keeps the residual check fail-closed instead of an exact allowlist
+    # that silently misses variants:
+    #   GPS*       — GPS plus any sub-group
+    #   XMP-*      — every XMP namespace (XMP-exif GPS, XMP-mwg-rs face/person
+    #                names, XMP-xmpMM DocumentID, XMP-iptcExt, …)
+    #   MakerNotes*, IPTC*
+    #   IFD1       — the embedded thumbnail IFD; a surviving thumbnail can carry
+    #                the original's full EXIF+GPS
+    # Over-flagging here is deliberate: for a privacy tool a false "still
+    # present" is far cheaper than a false "Cleaned". (ICC colour-profile groups
+    # are intentionally NOT flagged — a colour profile isn't PII; any genuinely
+    # identifying field such as Copyright is still caught by PRIVACY_TAGS below.)
+    PRIVACY_GROUP_PREFIXES = %w[GPS XMP- MakerNotes IPTC IFD1].freeze
+
+    # Formats ExifTool can't WRITE, so it leaves document-internal metadata only
+    # mat2's rebuild removes (and can't re-read to verify). If mat2 won't run for
+    # one of these, the runner warns coverage is reduced rather than reporting a
+    # confident "Cleaned". (PDF is NOT here: ExifTool writes PDF metadata and qpdf
+    # rebuilds the file, so PDF is fully handled and verifiable without mat2.)
+    MAT2_ESSENTIAL = %w[docx xlsx pptx odt ods odp odg odf epub].freeze
 
     # Specific tag NAMES (regardless of group) we never want to leak.
     # If exiftool reports e.g. "EXIF:Artist" we still flag it because of the
-    # tag-name match, not the group.
+    # tag-name match, not the group. exiftool's `-all=` normally strips these,
+    # so this list is a fail-closed BACKSTOP: if any survive a strip we'd rather
+    # over-warn than report a confident "Cleaned".
     PRIVACY_TAGS = %w[
       Artist Author Creator Copyright Rights
       By-line By-lineTitle Credit Source Contact OwnerName
@@ -25,45 +43,70 @@ module Metaclean
       Software HostComputer ProcessingSoftware
       ImageDescription UserComment
       LastModifiedBy LastSavedBy LastAuthor
+      Make Model LensModel DateTimeOriginal CreateDate
+      Title Subject Keywords Description Category Producer Company Manager
+      CreationDate ModDate
+      XPAuthor XPComment XPSubject XPKeywords XPTitle Comment
     ].freeze
 
     # File extensions where mat2 is meaningfully stricter than ExifTool and
     # should run first. For other formats, ExifTool is the broader expert.
+    # (mkv/webm are NOT here — see FFMPEG_FORMATS; no mat2/ExifTool path writes
+    # Matroska.)
     MAT2_PREFERRED = %w[
-      pdf docx xlsx pptx odt ods odp odg epub png svg
-      mp4 avi mkv mov webm
+      docx xlsx pptx odt ods odp odg odf epub png svg
+      mp4 avi
     ].freeze
 
+    # Matroska containers. ExifTool is read-only for them and mat2 has no
+    # Matroska parser, so neither can strip mkv/webm. ffmpeg is the only tool in
+    # the set that can — it remuxes the container dropping all metadata while
+    # copying every stream verbatim (lossless, no re-encode).
+    FFMPEG_FORMATS = %w[mkv webm].freeze
+
+    # Raster formats mat2 cannot strip without DAMAGING the file: it rebuilds via
+    # Pillow, which recompresses JPEG/WebP (visible quality loss — a clean
+    # wallpaper drops ~65% in size with no metadata to remove) and downconverts
+    # TIFF (16-bit → 8-bit). ExifTool strips all of these completely and IN PLACE
+    # (pixels byte-identical), so ExifTool owns them and mat2 is skipped —
+    # cleaning metadata must never silently damage the file.
+    MAT2_DEGRADES = %w[jpg jpeg webp tif tiff].freeze
+
     module_function
 
     # Returns an ordered list of tool symbols (e.g. `[:mat2, :exiftool, :qpdf]`)
     # to run on `path`. The runner executes them in order; if one fails or
-    # is skipped, the next still runs.
-    #
-    # `prefer:` is a hash of user opt-outs from the CLI flags
-    # (--no-mat2, --exiftool-only, etc.). The pattern `prefer[:mat2] != false`
-    # treats both `nil` (not set) and `true` as "use it" — only an explicit
-    # `false` disables.
-    def tools_for(path, prefer: {})
-      ext = File.extname(path).downcase.delete('.')
+    # is skipped, the next still runs. The three tools are always used together
+    # for maximum coverage — there is no per-tool opt-out; a tool that isn't
+    # installed is simply left out (the `.available?`/`.supports?` checks).
+    def tools_for(path)
+      ext = Metaclean.ext_of(path)
       tools = []
 
       if ext == 'pdf'
-        # PDFs benefit from all three, in this order:
-        #   mat2 → cleans the high-level metadata + content streams it knows
-        #   exiftool → strips the Info dictionary (Author, Title, Producer)
-        #   qpdf → rebuilds the file, dropping any unreferenced bits
-        tools << :mat2     if prefer[:mat2]     != false && Mat2.available?
-        tools << :exiftool if prefer[:exiftool] != false
-        tools << :qpdf     if prefer[:qpdf]     != false && Qpdf.available?
-      elsif MAT2_PREFERRED.include?(ext) && prefer[:mat2] != false && Mat2.available?
+        # mat2 cleans PDFs by RASTERIZING every page (text → images): it destroys
+        # the text layer and balloons the file (~35×). So PDFs skip mat2 and use:
+        #   exiftool → strips the Info dictionary + XMP (Author, Title, Producer…)
+        #   qpdf → rebuilds the file, dropping unreferenced objects / old revisions
+        # Both are lossless and leave the text intact. (PDF JS/macros are out of
+        # scope — see README.)
+        tools << :exiftool
+        tools << :qpdf if Qpdf.available?
+      elsif FFMPEG_FORMATS.include?(ext)
+        # Matroska (mkv/webm): ffmpeg is the ONLY tool that can clean these.
+        # ExifTool still re-reads the result afterwards, so the residual check
+        # (the false-clean backstop) is not blind.
+        tools << :ffmpeg if Ffmpeg.available?
+      elsif MAT2_PREFERRED.include?(ext) && Mat2.available?
         # Office docs, modern image/video containers — mat2 leads.
         tools << :mat2
-        tools << :exiftool if prefer[:exiftool] != false
+        tools << :exiftool
       else
-        # Everything else (JPEG, MP3, RAW, …) — ExifTool is the gold standard.
-        tools << :exiftool if prefer[:exiftool] != false
-        tools << :mat2     if prefer[:mat2]     != false && Mat2.supports?(path)
+        # Everything else (JPEG, MP3, RAW, …) — ExifTool has the broadest coverage.
+        # mat2 still adds coverage for many, but NOT for rasters it would damage
+        # (MAT2_DEGRADES) — there ExifTool's in-place strip is complete and lossless.
+        tools << :exiftool
+        tools << :mat2 if Mat2.supports?(path) && !MAT2_DEGRADES.include?(ext)
       end
 
       tools
@@ -78,19 +121,55 @@ module Metaclean
     # "Artist" in EXIF). Combining the two keeps coverage broad without
     # having to enumerate every {group, tag} pair.
     def privacy_residual(meta)
-      meta.reject { |k, _| k == 'SourceFile' }.select do |k, _|
-        # ExifTool keys look like "GPS:GPSLatitude". Split on the first ":".
+      meta.select do |k, v|
+        # Skip SourceFile and the System/File/etc. groups — not user metadata.
+        next false unless Display.embedded_key?(k)
+
+        # ExifTool keys look like "GPS:GPSLatitude". Split on the first ":";
+        # no "Group:" prefix means the whole key is the tag name.
         group, tag = k.to_s.split(':', 2)
-        # Skip System/File/etc. — those aren't user metadata.
-        next false if Display::NON_METADATA_GROUPS.include?(group)
-
-        if tag.nil?
-          # No "Group:" prefix — the whole key is the tag name.
-          PRIVACY_TAGS.include?(group.to_s)
-        else
-          PRIVACY_GROUPS.include?(group) || PRIVACY_TAGS.include?(tag)
-        end
+        name = tag.nil? ? group.to_s : tag
+
+        # A zeroed/empty value is not a leak for un-removable container atoms like
+        # QuickTime:CreateDate (deletable only by zeroing, "0000:00:00 …") — without
+        # this every video would fail the gate on an already-zeroed date. GPS is the
+        # exception: 0,0 is a REAL location (Null Island) and a coordinate ExifTool
+        # reports as 0 (or null) must still be caught, so the blank exemption NEVER
+        # applies to GPS-family entries — the whole point of the fail-closed backstop.
+        gps = group.to_s.start_with?('GPS') || name.start_with?('GPS')
+        next false if !gps && blank_value?(v)
+
+        privacy_group?(group) || privacy_tag?(name)
       end
     end
+
+    # True when a value carries no information: empty, or only zeros plus date/time
+    # punctuation and the "Z" (UTC) marker — e.g. "0000:00:00 00:00:00", or the ASF
+    # variant "0000:00:00 00:00:00Z" that mat2 writes into WMV's mandatory date
+    # field. Only the digit 0 is stripped (never 1-9), so a real value like
+    # "59.9139", "Jane Doe", or a real "2024:..." date keeps other characters and
+    # is NOT blank. (GPS is exempt from this check entirely — see privacy_residual.)
+    def blank_value?(value)
+      s = value.to_s
+      s.strip.empty? || s.gsub(/[Z0\s:.+-]/, '').empty?
+    end
+
+    # A group is privacy-bearing if it matches one of the family prefixes
+    # (GPS, XMP-, MakerNotes, IPTC, IFD1).
+    def privacy_group?(group)
+      PRIVACY_GROUP_PREFIXES.any? { |p| group.to_s.start_with?(p) }
+    end
+
+    # A tag is privacy-bearing if it's in the exact list OR is any GPS* tag
+    # (GPSLatitude/GPSLongitude/GPSPosition/… regardless of group).
+    def privacy_tag?(tag)
+      t = tag.to_s
+      PRIVACY_TAGS.include?(t) || t.start_with?('GPS')
+    end
+
+    # Does this path need mat2 for adequate coverage? (See MAT2_ESSENTIAL.)
+    def mat2_essential?(path)
+      MAT2_ESSENTIAL.include?(Metaclean.ext_of(path))
+    end
   end
 end

data/lib/metaclean/version.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
-# ───────────────────────────────────────────────────────────────────────────
 # Single source of truth for the program's version.
 # Both the gemspec and `metaclean --version` read from here, so we only have
 # one place to bump.
-# ───────────────────────────────────────────────────────────────────────────
 
 module Metaclean
-  VERSION = '1.0.2'
+  VERSION = '4.0.1'
 end

data/lib/metaclean.rb

@@ -1,33 +1,82 @@
 # frozen_string_literal: true
 
-# ───────────────────────────────────────────────────────────────────────────
-# lib/metaclean.rb — the library's "front door".
-#
-# In Ruby, a module is a namespace. We put everything inside `Metaclean::*`
-# so we don't pollute the global namespace and so it's obvious where each
-# piece belongs.
-#
-# The `require` order matters: a file can only reference constants from
-# files already loaded. We load the smallest pieces first, then the bigger
-# ones that depend on them.
-# ───────────────────────────────────────────────────────────────────────────
-
-require 'metaclean/version'   # just defines VERSION
-require 'metaclean/display'   # ANSI colors and formatters (no deps)
-require 'metaclean/exiftool'  # ExifTool wrapper
-require 'metaclean/mat2'      # mat2 wrapper
-require 'metaclean/qpdf'      # qpdf wrapper
-require 'metaclean/strategy'  # picks which tools run for each file type
-require 'metaclean/runner'    # orchestrates a clean across many files
-require 'metaclean/cli'       # parses ARGV and calls Runner
+# Library entry point. require order matters: dependencies before dependents.
+
+require 'metaclean/version'
+require 'metaclean/display'
+require 'metaclean/exiftool'
+require 'metaclean/mat2'
+require 'metaclean/qpdf'
+require 'metaclean/ffmpeg'
+require 'metaclean/strategy'
+require 'metaclean/runner'
+require 'metaclean/cli'
 
 module Metaclean
-  # Custom exception classes. Inheriting from StandardError lets callers do
-  # `rescue Metaclean::Error` to catch any of our errors without accidentally
-  # catching things like NoMemoryError or SystemExit.
   class Error < StandardError; end
 
-  # A more specific error so the CLI can show a tailored install hint when
-  # ExifTool itself is missing.
-  class ExiftoolMissing < Error; end
+  # Raised by ensure_tools! when any of the four required external tools is not
+  # on PATH. metaclean runs ExifTool, mat2, qpdf and ffmpeg together and refuses
+  # to run without all of them.
+  class ToolsMissing < Error; end
+
+  # A path beginning with "-" is misread as an *option* by the tools we shell
+  # out to — e.g. exiftool's `-config FILE` loads and runs arbitrary Perl.
+  # Open3 argument arrays bypass the shell, but NOT the invoked tool's own
+  # option parser. Prefixing a leading-dash relative path with "./" makes it
+  # unambiguously a filename to every tool. Absolute paths and normal names
+  # pass through untouched. Used at every shell-out boundary.
+  def self.safe_path(path)
+    s = path.to_s
+    s.start_with?('-') ? File.join('.', s) : s
+  end
+
+  # Lower-cased, dot-stripped extension used for FORMAT ROUTING decisions
+  # (Strategy#tools_for, Strategy#mat2_essential?, Mat2.supports?). One
+  # definition so every routing path normalizes the extension identically —
+  # a future tweak (double extensions, locale-safe downcasing) lands once.
+  def self.ext_of(path)
+    File.extname(path.to_s).downcase.delete('.')
+  end
+
+  # Marker embedded in every staging-temp filename (Runner, Ffmpeg, Qpdf) and
+  # matched by Runner#skip?, so a leftover temp from an interrupted run is
+  # ignored on a later directory scan. One literal keeps the producers and the
+  # matcher from drifting (qpdf previously embedded a divergent
+  # ".metaclean.qpdf.tmp." that didn't contain this marker).
+  TMP_MARKER = '.metaclean.tmp.'
+
+  # Suffix of the default "<name>_clean.<ext>" outputs. Runner#build_clean_path
+  # writes it; CLEAN_OUTPUT_RE derives the loop-prevention match from it so the
+  # producer and Runner#skip? can't disagree.
+  CLEAN_SUFFIX = '_clean'
+
+  # Matches our own "<name>_clean.<ext>" outputs (with optional "_N" collision
+  # counter) so a recursive re-run doesn't re-clean them. Compiled once here,
+  # in the module body that runs after the requires, so CLEAN_SUFFIX exists.
+  CLEAN_OUTPUT_RE = /#{Regexp.escape(CLEAN_SUFFIX)}(_\d+)?\.[^.]+\z/
+
+  # Preflight: all four tools must be installed. We run them together for full
+  # coverage and to verify the strip, so a partial toolchain is not "good enough"
+  # — bail with one clear message naming what's missing and how to install
+  # everything. Called once by the CLI before any inspect/clean work.
+  def self.ensure_tools!
+    missing = []
+    missing << 'exiftool' unless Exiftool.available?
+    missing << 'mat2'     unless Mat2.available?
+    missing << 'qpdf'     unless Qpdf.available?
+    missing << 'ffmpeg'   unless Ffmpeg.available?
+    return if missing.empty?
+
+    raise ToolsMissing, <<~MSG
+      Missing required tool(s): #{missing.join(', ')}
+
+      metaclean needs ExifTool, mat2, qpdf and ffmpeg together. Install all four:
+        macOS:          brew install exiftool mat2 qpdf ffmpeg
+        Debian/Ubuntu:  sudo apt install libimage-exiftool-perl mat2 qpdf ffmpeg
+        Fedora:         sudo dnf install perl-Image-ExifTool mat2 qpdf ffmpeg
+        Arch:           sudo pacman -S perl-image-exiftool mat2 qpdf ffmpeg
+        Windows:        use WSL2 (https://learn.microsoft.com/windows/wsl/install) + the Debian/Ubuntu line
+    MSG
+  end
 end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: metaclean
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 4.0.1
 platform: ruby
 authors:
-- 26zl
+- Laurent Zogaj
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
-  metaclean is a small Ruby CLI that wraps ExifTool, mat2 and qpdf to strip
-  removable embedded tags (EXIF, IPTC, XMP, GPS, MakerNotes, ID3, document
+  metaclean is a small Ruby CLI that wraps ExifTool, mat2, qpdf and ffmpeg to
+  strip removable embedded tags (EXIF, IPTC, XMP, GPS, MakerNotes, ID3, document
   properties, etc.) from images, audio, video, PDFs and Office documents —
   and shows a before/after diff of what was removed.
 executables:
@@ -26,6 +26,7 @@ files:
 - lib/metaclean/cli.rb
 - lib/metaclean/display.rb
 - lib/metaclean/exiftool.rb
+- lib/metaclean/ffmpeg.rb
 - lib/metaclean/mat2.rb
 - lib/metaclean/qpdf.rb
 - lib/metaclean/runner.rb
@@ -37,7 +38,6 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   bug_tracker_uri: https://github.com/26zl/metaclean/issues
-  changelog_uri: https://github.com/26zl/metaclean/releases
   source_code_uri: https://github.com/26zl/metaclean
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -54,8 +54,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- ExifTool (https://exiftool.org) on PATH
-rubygems_version: 3.7.2
+- ExifTool (https://exiftool.org) on PATH — required
+- mat2 (https://github.com/jvoisin/mat2) on PATH — required
+- qpdf (https://qpdf.sourceforge.io) on PATH — required
+- ffmpeg (https://ffmpeg.org) on PATH — required
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Cross-platform CLI that strips file metadata with ExifTool, mat2 and qpdf.
+summary: CLI that strips file metadata with ExifTool, mat2, qpdf and ffmpeg.
 test_files: []