metaclean 4.0.1 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b514075fb238c6274263922e87d7218b6c27b86f46c07dfa6fe36e8a1387b382
-  data.tar.gz: 7eff78f7bd882717bc03cc6f98cb140faa4c9123d5b6a0806ccdb0e342cd3935
+  metadata.gz: 8e4ebafb7621f428c5a0d0040c2487340e2dd22b32b831bf47c957027e4d0ca9
+  data.tar.gz: e9420536e480b319833996372e9d679285289e5afdfe3555466ff8167ebf5d7f
 SHA512:
-  metadata.gz: b674107a22b4965a30bd5c990c90fec5d4944828a8ca755f27124029383de2a543fdf73fad42934b7fa6c4600d0670ffc79ff1602a9b23caf4da9bec7e239ccf
-  data.tar.gz: d265c366f6b7f0c76acd866e883dc8459ab4e35c27ef092abb4488262e4a5726f7b812d00bba5419282a47d05c80ac3e5e4b97254d2849f3bb4320d7cb19e5b8
+  metadata.gz: 6c9b8b897058f4b86d9691d53f80f1045d78f1783861048591f6910b92cfca25a1f0e7ee531a91d22144ebf294c1240a4dd46a465412cff7c1d3dcd85d421a4f
+  data.tar.gz: 5dcdfbd96dd879ddb8c6e86f2c48b29ac43672eb5636ea2fb5e2a3260cac0bf9bad7644bb594d05834e1267850d95034ff3b4780b5a54af9e60b6cc321ea47fd

data/README.md

@@ -19,7 +19,7 @@ A small Ruby CLI that strips metadata from almost any file —
 images, audio, video, PDFs, Office documents — and shows a colored before/after
 diff of exactly what was removed.
 
-It wraps four battle-tested tools and routes each file to the right one:
+It wraps four external tools and routes each file to the right one:
 
 - **ExifTool** — the broadest format coverage (EXIF, IPTC, XMP, GPS, ID3, …)
 - **mat2** — stricter on `.docx` / `.png` and Office/OpenDocument files (rebuilds the file)
@@ -28,14 +28,19 @@ It wraps four battle-tested tools and routes each file to the right one:
 
 ## Why metaclean?
 
-- **Verification-first:** it re-reads the cleaned file and refuses to write a
-  result when known privacy metadata survives.
+- **Verification-first:** it re-reads the cleaned file and only commits a
+  result whose final status is `cleaned`; failed, unsupported and unverified
+  candidates are deleted.
 - **Safer defaults:** it writes `*_clean` copies by default; `--in-place` keeps a
-  `.bak` and asks for confirmation unless `--force` is set.
-- **Lossless routing:** it avoids mat2 paths that recompress JPEG/WebP or
-  downconvert TIFF, and uses ffmpeg stream-copy for Matroska.
-- **Batch-friendly:** failed or unverified files exit non-zero, so scripts and CI
-  do not mistake uncertainty for success.
+  `.bak` and asks for confirmation unless `--force` is set. Note the `.bak` is the
+  **original, with all its metadata** — delete or move the `.bak` files before
+  sharing an in-place-cleaned folder.
+- **Content-preserving routing:** it keeps image orientation, avoids lossy
+  raster paths, and preserves Matroska chapters and languages.
+- **Nested-content guard:** PDFs and Matroska files with attachments or cover
+  art fail closed until their embedded payloads can be independently cleaned.
+- **Batch-friendly:** failed, unsupported or unverified files exit non-zero, so
+  scripts and CI do not mistake uncertainty for success.
 
 ## What it looks like
 
@@ -85,7 +90,6 @@ From a source checkout:
 
 ```bash
 git clone https://github.com/26zl/metaclean.git && cd metaclean
-chmod +x bin/metaclean
 bundle install
 bundle exec rake install
 metaclean --version
@@ -140,8 +144,11 @@ metaclean --in-place photo.jpg
 # Clean a whole folder, recursively, no prompts
 metaclean -r --in-place --force ./vacation
 
-# See what would change without writing anything
+# See what would change; a private temporary copy is removed afterwards
 metaclean --dry-run photo.jpg
+
+# Avoid writing private metadata values to a log
+metaclean --redact-values photo.jpg
 ```
 
 ## Flags
@@ -149,34 +156,87 @@ metaclean --dry-run photo.jpg
 | Flag | What it does |
 | --- | --- |
 | `--inspect` | Read-only — print metadata, never write |
-| `--dry-run` | Simulate cleaning, show diff, write nothing |
-| `-i`, `--in-place` | Overwrite originals (keeps a `<file>.bak`) |
+| `--dry-run` | Simulate on a private mode-0700 temporary copy; keep no output |
+| `-i`, `--in-place` | Overwrite originals (keeps a `<file>.bak` — the **original, metadata intact**; remove it before sharing) |
 | `-r`, `--recursive` | Recurse into directories |
 | `-f`, `--force` | Skip the confirmation prompt |
+| `-q`, `--quiet` | Suppress normal output; warnings and errors remain |
+| `--redact-values` | Hide metadata values in tables and diffs |
+| `--show-values` | Show values even when stdout is redirected |
+| `--allow-icc-metadata` | Keep a non-standard ICC profile's identifying text; recognized standard color spaces (sRGB, Display P3, …) clean without it |
 | `-h`, `--help` | Show usage and exit |
 | `-v`, `--version` | Show metaclean's version **and** the detected versions of exiftool/mat2/qpdf/ffmpeg (prints `not found` for any missing) |
 
+Exit codes are `0` for a fully successful batch, `1` for failed, unsupported,
+unverified or incomplete work, `2` for a missing toolchain, and `130` for
+Ctrl-C.
+
+## Supported formats
+
+Routing covers the formats supported by the installed toolchain, including:
+
+- images: JPEG, PNG, GIF, BMP, TIFF, WebP, HEIC, PPM, SVG and DNG;
+- audio/video: MP3, FLAC, Ogg/Opus, WAV, AIFF, MP4/M4A/MOV, AVI, WMV and Matroska;
+- documents: PDF, OOXML, OpenDocument, EPUB, HTML/XHTML and CSS;
+- archives/data: ZIP, TAR and BitTorrent files.
+
+Support still depends on the installed ExifTool/mat2/qpdf/ffmpeg versions.
+Unknown or unsupported formats are never treated as success. PDFs and Matroska
+files containing attachments or cover-art streams are reported unverified or
+failed and are not written.
+
+ICC profiles are retained because removing them can change color rendering.
+Recognized standard color spaces (sRGB, Display P3, Adobe RGB, the generic
+profiles, …) are shared by countless files and are not identifying, so they
+clean normally. A profile whose description is not a known standard can carry a
+person's or organization's name in its description, creator, manufacturer or
+copyright fields, so it blocks commit by default — review it and pass
+`--allow-icc-metadata` to keep it.
+
 ## Publishing
 
-The release workflow builds a `.gem` for every `v*` tag, attaches it to a
-GitHub Release, and publishes it to RubyGems via a
+The release workflow accepts a matching `v*` tag only when its commit belongs
+to `main`. It tests every supported Ruby version, builds a `.gem`, attaches it
+to a GitHub Release, and publishes it to RubyGems via a
 [Trusted Publisher](https://guides.rubygems.org/trusted-publishing/) (OIDC) —
 `rubygems/release-gem` with `id-token: write`. There is **no `RUBYGEMS_API_KEY`
 secret**; the one-time prerequisite is registering this gem's Trusted Publisher
 on rubygems.org.
 
+Replace `X.Y.Z` with the version in `lib/metaclean/version.rb` — the release
+workflow refuses to publish if the tag and that version disagree.
+
 ```bash
-git tag v3.0.0
-git push origin v3.0.0
+git tag vX.Y.Z
+git push origin vX.Y.Z
 ```
 
 ## Safety
 
-- All shell-outs use argument arrays (`Open3.capture3(*args)`), so filenames
-  with spaces, quotes, or shell metacharacters are safe.
-- `--in-place` writes atomically: the file is built in a temp file and
-  renamed into place, so a crash mid-run cannot leave a half-written original.
-- Symlinks are always skipped — metaclean never cleans through a link.
+- All shell-outs use argument arrays (no shell is involved), so filenames with
+  spaces, quotes, or shell metacharacters are safe.
+- Each external tool, including version probes, runs under a wall-clock timeout
+  and output cap. Cleaning defaults to 120 s; probes use a shorter limit. For
+  very large media on slow or network storage, raise the timeout with
+  `METACLEAN_TIMEOUT=<seconds>` (e.g. `METACLEAN_TIMEOUT=600`).
+- Tool output is created inside a private mode-0700 workspace and is rejected
+  if it is a symlink or non-regular file. Normal commits stage on the destination
+  filesystem for atomic rename; dry-run uses the system temp area. metaclean
+  fails instead of proceeding when private permissions cannot be enforced.
+- `--in-place` builds the clean file privately, verifies that the source has not
+  changed, preserves ownership/permissions/ACLs/extended attributes with the
+  host's native `cp`, creates the metadata-bearing `.bak`, and then renames into
+  place. Failure to preserve these attributes or create a hard-link backup
+  aborts the commit; use the default `*_clean` mode on filesystems without hard
+  links.
+- Final symlinks and user-controlled symlinks in parent path components are
+  rejected. Parent-directory identities are checked again before commit.
+- Folder and recursive (`-r`) scans deliberately skip hidden files and hidden
+  directories, plus metaclean's outputs (`*_clean`, `*_clean.*`, `*.bak`).
+  Name a hidden file explicitly if it should be cleaned.
+- A `<file>.bak` left by `--in-place` is the **untouched original** and still
+  contains all its metadata. Its actual collision-safe path is reported even
+  with `--force`, but it is yours to delete or move before sharing the folder.
 - Filename collisions (`photo_clean.jpg` already exists, `.bak` already
   exists) are resolved with `_1`, `_2`, … suffixes, including late collisions
   that appear while a file is being cleaned.
@@ -189,14 +249,20 @@ git push origin v3.0.0
 - metaclean requires ExifTool, mat2, qpdf, and ffmpeg, and refuses to run (with
   install instructions, exit code 2) if any is missing — so the post-clean
   residual check always runs.
-- Naming no files (a missing path, or everything filtered out), failed files,
-  and unverified cleans exit non-zero, so scripts do not mistake uncertainty for
-  success.
+- Naming no files, discovery errors, unsupported formats, failed files and
+  unverified candidates all exit non-zero.
+- When stdout is redirected, metadata values are redacted by default. Use
+  `--show-values` only when the destination log is trusted.
+- External tool versions are recorded in CI and shown by `metaclean --version`.
+  Keep OS packages updated; release tests exercise the supported Ruby range and
+  capability-check qpdf/ffmpeg output rather than trusting version strings.
 
 ## What it does *not* do
 
 - Steganography (data hidden inside the pixel/audio data itself).
-- Filesystem metadata (mtime, ownership) — that's the OS, not the file.
+- Renaming files or directories, or removing filesystem timestamps. In-place
+  mode preserves filesystem security metadata; a new `*_clean` copy naturally
+  has a new inode.
 - Office macros or PDF JavaScript — open untrusted files in a sandbox.
 
 The post-clean "still present" check is bounded by what ExifTool can re-read.
@@ -205,6 +271,11 @@ For container formats that mat2 cleans but ExifTool only partially parses (e.g.
 independently confirm — a clean report means "the tools ran", not "every byte
 was audited".
 
+Nested files are a separate trust boundary. PDF attachments and Matroska
+attachments/cover art currently fail closed instead of being preserved under a
+false clean result. Archive/document formats are accepted only when their
+cleaning tool completes; do not treat metaclean as a malware scanner.
+
 **SVG:** some mat2 builds (e.g. 0.14.0 on recent Python) crash on SVG, and
 ExifTool is read-only for it — so on those systems metaclean cannot clean
 `.svg`. It reports the file as **failed** (exit 1) and leaves the original

data/SECURITY.md

@@ -0,0 +1,59 @@
+# Security Policy
+
+metaclean is a privacy tool: its worst-case failure is reporting a file as
+"clean" when removable metadata actually survived, or mishandling a file it
+overwrites. Reports of either — or of any vulnerability in metaclean itself —
+are welcome.
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for security reports.**
+
+Use GitHub's [private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
+for this repository (the **Security** tab → **Report a vulnerability**). If that
+is unavailable, contact the maintainer privately via their GitHub profile
+([@26zl](https://github.com/26zl)).
+
+Please include:
+
+- the file type and a minimal way to reproduce (use `--dry-run` if you can't
+  share the file);
+- the metaclean version and the detected exiftool/mat2/qpdf/ffmpeg versions
+  (`metaclean --version`);
+- your OS and Ruby version.
+
+We aim to acknowledge reports within a few days.
+
+## Scope
+
+metaclean shells out to **ExifTool**, **mat2**, **qpdf**, and **ffmpeg**, which
+parse hostile binary formats and have had CVEs of their own. Vulnerabilities in
+those tools should be reported to their respective projects — keep them updated. metaclean's
+own scope is the wrapper logic: path handling and argument-injection guards,
+private temporary workspaces, the strip/verify pipeline, and the guarantee that
+failed, unsupported or unverified candidates are never committed as clean.
+
+Tool output is created in a mode-0700 directory (on the destination filesystem
+for real commits, in system temp for dry-run) and validated with `lstat` before commit. Reports that bypass this boundary,
+cause a symlink to be committed, or overwrite an unrelated file are in scope.
+User-controlled symlinks in parent path components are rejected and path
+component identities are pinned from discovery through commit.
+
+Embedded payloads are treated as a separate verification boundary. PDFs and
+Matroska files containing attachments or cover-art streams are rejected because
+their nested metadata cannot yet be independently verified. A file reported
+clean while such metadata survives is a security issue.
+
+A non-standard ICC profile (one whose description is not a recognized standard
+color space) blocks commit unless the user explicitly accepts its identifying
+fields with `--allow-icc-metadata`; standard color spaces clean without it.
+
+## Supported versions
+
+metaclean follows [Semantic Versioning](https://semver.org). Only the latest
+released version receives fixes.
+
+The external parsers are supplied by the operating system rather than the gem.
+CI records their versions and capability-checks the features metaclean uses, but
+users must keep ExifTool, mat2, qpdf and ffmpeg patched through their package
+manager.

data/bin/metaclean

@@ -1,7 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Add <repo>/lib to the load path so this runs from a checkout, gem or not.
 $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
 require 'metaclean'
 

data/lib/metaclean/cli.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# CLI argument parser. Uses stdlib OptionParser (zero deps) over a gem like Thor.
-
 require 'optparse'
 
 module Metaclean
@@ -17,23 +15,18 @@ module Metaclean
         in_place:     false,
         force:        false,
         inspect_only: false,
-        dry_run:      false
+        dry_run:      false,
+        quiet:        false,
+        allow_icc_metadata: false,
+        redact_values: !$stdout.tty?
       }
       @paths = []
     end
 
-    # Top-level dispatcher. Catches our errors and exits with codes that
-    # shells/CI can act on:
-    #   0  → success
-    #   1  → general failure
-    #   2  → a required tool (exiftool/mat2/qpdf/ffmpeg) is missing (install hint shown)
-    #   130→ user pressed Ctrl-C (matches the standard SIGINT exit code)
     def run
       parse!
-      # Refuse to run unless all four external tools are present (see
-      # Metaclean.ensure_tools!). --help/--version already exited inside parse!,
-      # so this only gates an actual inspect/clean.
-      Metaclean.ensure_tools!
+      Display.configure(quiet: @options[:quiet], redact_values: @options[:redact_values])
+      Metaclean.ensure_tools!(in_place: @options[:in_place])
       runner = Runner.new(@options)
       if @options[:inspect_only]
         runner.inspect_paths(@paths)
@@ -45,13 +38,9 @@ module Metaclean
       warn e.message
       exit 2
     rescue Error, SystemCallError => e
-      # Errno::* (disk full, permission denied, read-only fs) is a SIBLING of
-      # our Error, not a subclass; naming it here gives filesystem failures a
-      # clean message + exit 1 instead of a raw backtrace.
       warn Display.error(e.message)
       exit 1
     rescue Interrupt
-      # Print a clean message instead of a stack trace.
       warn "\n#{Display.error('Interrupted.')}"
       exit 130
     end
@@ -59,7 +48,36 @@ module Metaclean
     private
 
     def parse!
-      parser = OptionParser.new do |o|
+      parser = option_parser
+
+      begin
+        parser.parse!(@argv)
+      rescue OptionParser::ParseError => e
+        warn Display.error(e.message)
+        warn parser
+        exit 1
+      end
+
+      if @argv.empty?
+        Display.banner
+        puts parser
+        exit 1
+      end
+
+      incompatible = []
+      incompatible << '--dry-run' if @options[:dry_run]
+      incompatible << '--in-place' if @options[:in_place]
+      incompatible << '--force' if @options[:force]
+      if @options[:inspect_only] && incompatible.any?
+        warn Display.error("--inspect cannot be combined with #{incompatible.join(', ')}")
+        exit 1
+      end
+
+      @paths = @argv.dup
+    end
+
+    def option_parser
+      OptionParser.new do |o|
         o.banner = 'Usage: metaclean [options] <path> [<path>...]'
         o.separator ''
         o.separator 'Metadata cleaner. Strips EXIF, IPTC, XMP, GPS,'
@@ -69,13 +87,20 @@ module Metaclean
 
         o.separator 'Modes:'
         o.on('--inspect', 'Only show metadata, do not modify files')     { @options[:inspect_only] = true }
-        o.on('--dry-run', 'Simulate cleaning, show diff, write nothing') { @options[:dry_run] = true }
+        o.on('--dry-run', 'Simulate on a private temporary copy; keep no output') { @options[:dry_run] = true }
 
         o.separator ''
         o.separator 'Output:'
         o.on('-i', '--in-place', 'Overwrite originals (keeps a .bak; default: *_clean.<ext>)') { @options[:in_place] = true }
         o.on('-r', '--recursive', 'Recurse into directories') { @options[:recursive] = true }
         o.on('-f', '--force',     'Skip confirmation prompt')  { @options[:force] = true }
+        o.on('-q', '--quiet',     'Suppress normal output; errors and warnings remain') { @options[:quiet] = true }
+        o.on('--redact-values',   'Hide metadata values in tables and diffs') { @options[:redact_values] = true }
+        o.on('--show-values',     'Show metadata values even when output is redirected') { @options[:redact_values] = false }
+        o.on('--allow-icc-metadata',
+             'Keep non-standard ICC profile text (standard color spaces clean anyway)') do
+          @options[:allow_icc_metadata] = true
+        end
 
         o.separator ''
         o.separator 'Other:'
@@ -83,37 +108,15 @@ module Metaclean
         o.on('-v', '--version') do
           Display.banner
           puts "metaclean #{Metaclean::VERSION}"
-          # Route tool versions (from the binaries' own stdout) through printable,
-          # like every other output path, so a tool emitting ANSI/OSC control
-          # bytes on its version line can't inject the terminal.
           puts "  exiftool: #{Display.printable(Exiftool.version || 'not found')}"
           puts "  mat2:     #{Display.printable(Mat2.version     || 'not found')}"
           puts "  qpdf:     #{Display.printable(Qpdf.version     || 'not found')}"
           puts "  ffmpeg:   #{Display.printable(Ffmpeg.version   || 'not found')}"
           exit
         end
+        o.separator ''
+        o.separator 'Use -- before a filename that begins with "-".'
       end
-
-      begin
-        parser.parse!(@argv)
-      rescue OptionParser::ParseError => e
-        # Any malformed flag — unknown, missing argument, or an ambiguous
-        # abbreviation like `--i` (matches both --inspect and --in-place) —
-        # shows the message + help and exits non-zero, never a raw backtrace.
-        # ParseError is the base class of all of OptionParser's error types.
-        warn Display.error(e.message)
-        warn parser
-        exit 1
-      end
-
-      # No paths: show help, exit non-zero so scripts notice.
-      if @argv.empty?
-        Display.banner
-        puts parser
-        exit 1
-      end
-
-      @paths = @argv.dup
     end
   end
 end

data/lib/metaclean/committer.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tmpdir'
+
+module Metaclean
+  class Committer
+    def initialize(in_place: false, dry_run: false)
+      @in_place = in_place
+      @dry_run = dry_run
+    end
+
+    def resolve_final_path(file)
+      return file if @in_place
+
+      collision_safe(build_clean_path(file))
+    end
+
+    def staging_path_for(final_path)
+      prefix = "#{Metaclean::TMP_MARKER}runner.#{Process.pid}."
+      workspace = if @dry_run
+                    Dir.mktmpdir(prefix)
+                  else
+                    Dir.mktmpdir(prefix, File.dirname(final_path))
+                  end
+      FileOps.secure_workspace!(workspace)
+      File.join(workspace, "staging#{File.extname(final_path)}")
+    rescue StandardError, Interrupt
+      FileUtils.remove_entry(workspace, true) if workspace && File.exist?(workspace)
+      raise
+    end
+
+    def cleanup_staging(staging)
+      return unless staging
+
+      workspace = File.dirname(staging)
+      FileUtils.remove_entry(workspace, true) if File.exist?(workspace)
+    end
+
+    def commit!(staging, final_path, source_stat:)
+      backup = nil
+      committed = false
+      if @in_place
+        FileOps.ensure_same_file!(final_path, source_stat)
+        backup = backup_original(final_path, source_stat)
+        File.rename(staging, final_path)
+        committed = true
+        return { path: final_path, backup: backup }
+      end
+
+      { path: link_with_collision_safe_name(staging, final_path), backup: nil }
+    rescue SystemCallError, Interrupt
+      if backup && !committed && File.exist?(staging) && FileOps.lexist?(backup)
+        File.delete(backup)
+      end
+      raise
+    end
+
+    def backup_original(final_path, source_stat)
+      backup = hardlink_with_collision_safe_name(final_path, "#{final_path}.bak")
+      unless FileOps.same_identity?(File.lstat(backup), source_stat)
+        File.delete(backup)
+        raise Error, "#{final_path} changed during cleaning — refusing to back it up"
+      end
+      backup
+    rescue Errno::EACCES, Errno::EPERM, Errno::ENOTSUP, Errno::EMLINK, NotImplementedError => e
+      raise Error, "Cannot create a metadata-preserving hard-link backup: #{e.message}; use default copy mode"
+    end
+
+    def hardlink_with_collision_safe_name(source, preferred)
+      target = preferred
+      loop do
+        File.link(source, target)
+        return target
+      rescue Errno::EEXIST
+        target = collision_safe(preferred)
+      end
+    end
+
+    def link_with_collision_safe_name(staging, preferred)
+      target = preferred
+      loop do
+        File.link(staging, target)
+        File.delete(staging)
+        return target
+      rescue Errno::EEXIST
+        target = collision_safe(preferred)
+      rescue Errno::EACCES, Errno::EPERM, Errno::ENOTSUP, Errno::EMLINK, NotImplementedError
+        target = copy_with_collision_safe_name(staging, target)
+        File.delete(staging)
+        return target
+      end
+    end
+
+    def copy_with_collision_safe_name(source, preferred, expected: nil)
+      target = preferred
+      loop do
+        copy_file_exclusive(source, target, preserve: true, expected: expected)
+        return target
+      rescue Errno::EEXIST
+        target = collision_safe(preferred)
+      end
+    end
+
+    def copy_file_exclusive(source, destination, preserve: false, expected: nil)
+      FileOps.copy_exclusive(source, destination, preserve: preserve, expected: expected)
+    end
+
+    def build_clean_path(file)
+      extension = File.extname(file)
+      base = File.basename(file, extension)
+      File.join(File.dirname(file), "#{base}#{Metaclean::CLEAN_SUFFIX}#{extension}")
+    end
+
+    def collision_safe(path)
+      return path unless FileOps.lexist?(path)
+
+      extension = File.extname(path)
+      base = File.basename(path, extension)
+      directory = File.dirname(path)
+      index = 1
+      loop do
+        candidate = File.join(directory, "#{base}_#{index}#{extension}")
+        return candidate unless FileOps.lexist?(candidate)
+
+        index += 1
+      end
+    end
+  end
+end

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