excavate 1.0.3 → 1.1.1

data/lib/excavate/archive.rb

@@ -1,48 +1,39 @@
+# frozen_string_literal: true
+
 module Excavate
   class Archive
-    INVALID_MEMORY_MESSAGE =
-      "invalid memory read at address=0x0000000000000000".freeze
-
-    TYPES = { "cab" => Extractors::CabExtractor,
-              "cpio" => Extractors::CpioExtractor,
-              "exe" => Extractors::SevenZipExtractor,
-              "gz" => Extractors::GzipExtractor,
-              "msi" => Extractors::OleExtractor,
-              "pkg" => Extractors::XarExtractor,
-              "rpm" => Extractors::RpmExtractor,
-              "tar" => Extractors::TarExtractor,
-              "xz" => Extractors::XzExtractor,
-              "zip" => Extractors::ZipExtractor }.freeze
-
     def initialize(archive)
       @archive = archive
     end
 
-    def files(recursive_packages: false, files: [], filter: nil, &)
-      # Auto-enable recursive_packages when extracting specific files
+    def files(recursive_packages: false, files: [], filter: nil, &block)
+      unless block
+        return enum_for(:files, recursive_packages: recursive_packages,
+                                files: files, filter: filter)
+      end
+
       recursive_packages = true if files.any?
 
       target = Dir.mktmpdir
       extract(target, recursive_packages: recursive_packages,
                       files: files, filter: filter)
 
-      all_files_in(target).map(&)
+      all_files_in(target).each(&block)
     ensure
-      windows_safe_rm_rf(target)
+      Filesystem.remove_recursive(target) if target
     end
 
     def extract(target = nil,
                 recursive_packages: false,
                 files: [],
                 filter: nil)
-      # Auto-enable recursive_packages when extracting specific files
       recursive_packages = true if files.any?
 
       if files.size.positive?
-        extract_particular_files(target, files,
-                                 recursive_packages: recursive_packages)
+        extract_selection(target, Selection.from_files(files),
+                          recursive_packages: recursive_packages)
       elsif filter
-        extract_by_filter(target, filter,
+        extract_selection(target, Selection.from_filter(filter),
                           recursive_packages: recursive_packages)
       else
         extract_all(target, recursive_packages: recursive_packages)
@@ -51,20 +42,20 @@ module Excavate
 
     private
 
-    def extract_particular_files(target, files, recursive_packages: false)
+    def extract_selection(target, selection, recursive_packages: false)
       tmp = Dir.mktmpdir
       extract_all(tmp, recursive_packages: recursive_packages)
-      found_files = find_files(tmp, files)
-      copy_files(found_files, target || Dir.pwd)
+      found = selection.match(all_files_in(tmp), tmp)
+      copy_files(found, target || Dir.pwd)
     ensure
-      FileUtils.rm_rf(tmp)
+      Filesystem.remove_recursive(tmp) if tmp
     end
 
     def copy_files(files, target)
+      FileUtils.mkdir_p(target)
       files.map do |file|
-        FileUtils.mkdir_p(target)
         target_path = File.join(target, File.basename(file))
-        ensure_not_exist(target_path)
+        ensure_target_absent(target_path)
 
         FileUtils.cp(file, target_path)
 
@@ -72,69 +63,10 @@ module Excavate
       end
     end
 
-    def ensure_not_exist(path)
-      if File.exist?(path)
-        type = File.directory?(path) ? "directory" : "file"
-        raise(TargetExistsError,
-              "Target #{type} `#{File.basename(path)}` already exists.")
-      end
-    end
-
-    def find_files(source, files)
-      all_files = all_files_in(source)
-
-      files.map do |target_file|
-        found_file = all_files.find do |source_file|
-          file_matches?(source_file, target_file, source)
-        end
-
-        unless found_file
-          raise(TargetNotFoundError, "File `#{target_file}` not found.")
-        end
-
-        found_file
-      end
-    end
-
-    def file_matches?(source_file, target_file, source_dir)
-      base_path(source_file, source_dir) == target_file
-    end
-
-    def base_path(path, prefix)
-      path.sub(prefix, "").sub(/^\//, "").sub(/^\\/, "")
-    end
-
-    def extract_by_filter(target, filter, recursive_packages: false)
-      tmp = Dir.mktmpdir
-      extract_all(tmp, recursive_packages: recursive_packages)
-      found_files = find_by_filter(tmp, filter)
-      copy_files(found_files, target || Dir.pwd)
-    ensure
-      FileUtils.rm_rf(tmp)
-    end
-
-    def find_by_filter(source, filter)
-      all_files = all_files_in(source)
-
-      found_files = all_files.select do |source_file|
-        file_matches_filter?(source_file, filter, source)
-      end
-
-      if found_files.empty?
-        raise(TargetNotFoundError, "Filter `#{filter}` matched no file.")
-      end
-
-      found_files
-    end
-
-    def file_matches_filter?(source_file, filter, source_dir)
-      File.fnmatch?(filter, base_path(source_file, source_dir))
-    end
-
     def extract_all(target, recursive_packages: false)
       source = File.expand_path(@archive)
       target ||= default_target(source)
-      ensure_empty(target)
+      ensure_target_empty(target)
 
       if recursive_packages
         extract_recursively(source, target)
@@ -145,19 +77,25 @@ module Excavate
       target
     end
 
-    def ensure_empty(path)
-      unless Dir.empty?(path)
-        raise(TargetNotEmptyError,
-              "Target directory `#{File.basename(path)}` is not empty.")
-      end
+    def ensure_target_absent(path)
+      return unless File.exist?(path)
+
+      kind = File.directory?(path) ? "directory" : "file"
+      raise TargetExistsError,
+            "Target #{kind} `#{File.basename(path)}` already exists."
+    end
+
+    def ensure_target_empty(path)
+      return if Dir.empty?(path)
+
+      raise TargetNotEmptyError,
+            "Target directory `#{File.basename(path)}` is not empty."
     end
 
     def default_target(source)
       target = File.expand_path(File.basename(source, ".*"))
-      ensure_not_exist(target)
-
+      ensure_target_absent(target)
       FileUtils.mkdir(target)
-
       target
     end
 
@@ -175,7 +113,7 @@ module Excavate
       if File.directory?(archive)
         duplicate_dir(archive, target)
       elsif !archive?(archive)
-        copy_file(archive, target)
+        FileUtils.cp(archive, target)
       else
         extract_once(archive, target)
       end
@@ -189,27 +127,17 @@ module Excavate
       end
     end
 
-    def copy_file(archive, target)
-      FileUtils.cp(archive, target)
-    end
-
-    def may_be_nested_cab?(extension, message)
-      extension == "exe" &&
-        (message.start_with?("Invalid file format",
-                             "Unrecognized archive format") ||
-         message.include?("Invalid .7z signature"))
-    end
-
     def extract_once(archive, target)
-      extension = normalized_extension(archive)
-      extractor_class = TYPES[extension]
+      type = FileMagic.detect(archive)
+      extractor_class = Extractors::Extractor.for_magic_type(type)
       unless extractor_class
-        raise(UnknownArchiveError, "Could not unarchive `#{archive}`.")
+        raise UnknownArchiveError,
+              "Could not unarchive `#{archive}`."
       end
 
       extractor_class.new(archive).extract(target)
     rescue StandardError => e
-      raise unless may_be_nested_cab?(extension, e.message)
+      raise unless NestedCabFallback.applies_to?(type, e)
 
       Extractors::CabExtractor.new(archive).extract(target)
     end
@@ -217,81 +145,15 @@ module Excavate
     def extract_and_replace(archive)
       target = Dir.mktmpdir
       extract_recursively(archive, target)
-      replace_archive_with_contents(archive, target)
+      Filesystem.replace_with_contents(archive, target)
     rescue StandardError
       # During recursive extraction of nested archives, silently skip
       # any that fail (e.g. .msi files that aren't real OLE, .cab files
       # with incompatible format, .exe files with unsupported compression).
-      # Only re-raise for file types we don't recognize as archives.
-      raise unless TYPES.key?(normalized_extension(archive))
+      # Only re-raise if the file is not a recognized archive format.
+      raise unless File.exist?(archive) && archive?(archive)
     ensure
-      FileUtils.rm_rf(target)
-    end
-
-    def replace_archive_with_contents(archive, target)
-      windows_safe_rm(archive)
-      FileUtils.mv(target, archive)
-    rescue Errno::EACCES
-      # Windows: file is locked. Copy extracted contents to archive location
-      # and keep both the archive and extracted files
-      target_dir = File.dirname(archive)
-      # Copy all extracted files to the target directory
-      Dir.glob(File.join(target, "**", "*")).each do |src|
-        next unless File.file?(src)
-
-        dest = File.join(target_dir, File.basename(src))
-        FileUtils.cp(src, dest) unless File.exist?(dest)
-      end
-      # Leave the original locked archive in place
-    end
-
-    # Windows sometimes holds file locks briefly after operations.
-    # This method retries file deletion with a small delay.
-    def windows_safe_rm(path, max_retries: 5)
-      attempts = 0
-      begin
-        FileUtils.rm(path)
-      rescue Errno::EACCES => e
-        attempts += 1
-        if attempts < max_retries
-          sleep(0.2)
-          retry
-        else
-          raise e
-        end
-      end
-    end
-
-    # Windows-safe recursive removal
-    def windows_safe_rm_rf(path, max_retries: 5)
-      attempts = 0
-      begin
-        FileUtils.rm_rf(path)
-      rescue Errno::EACCES, Errno::ENOTEMPTY => e
-        attempts += 1
-        if attempts < max_retries
-          sleep(0.2)
-          retry
-        else
-          raise e
-        end
-      end
-    end
-
-    def normalized_extension(file)
-      fetch_extension(file).downcase
-    end
-
-    def fetch_extension(file)
-      File.extname(filename(file)).sub(/^\./, "")
-    end
-
-    def filename(file)
-      if file.respond_to?(:original_filename)
-        file.original_filename
-      else
-        File.basename(file)
-      end
+      Filesystem.remove_recursive(target) if target
     end
 
     def all_files_in(dir)
@@ -301,10 +163,8 @@ module Excavate
     def archive?(file)
       return false unless File.file?(file)
 
-      ext = normalized_extension(file)
-      return false if ext == "gz" && FileMagic.detect(file) != :gzip
-
-      TYPES.key?(ext)
+      type = FileMagic.detect(file)
+      !type.nil? && !Extractors::Extractor.for_magic_type(type).nil?
     end
   end
 end

data/lib/excavate/cli.rb

@@ -1,7 +1,5 @@
 require "thor"
 
-require_relative "../excavate"
-
 module Excavate
   class CLI < Thor
     STATUS_SUCCESS = 0

data/lib/excavate/extractors/cab_extractor.rb

@@ -5,6 +5,8 @@ require "cabriolet"
 module Excavate
   module Extractors
     class CabExtractor < Extractor
+      handles :cab
+
       def extract(target)
         decompressor = Cabriolet::CAB::Decompressor.new
         decompressor.salvage = true # Enable salvage mode for compatibility

data/lib/excavate/extractors/cpio_extractor.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
-require "omnizip/formats/cpio"
+require "omnizip"
 
 module Excavate
   module Extractors
     class CpioExtractor < Extractor
+      handles :cpio
+
       def extract(target)
         reader = Omnizip::Formats::Cpio::Reader.new(@archive)
         reader.open

data/lib/excavate/extractors/extractor.rb

@@ -1,12 +1,83 @@
+# frozen_string_literal: true
+
 module Excavate
   module Extractors
+    # Base class for all archive extractors.
+    #
+    # Subclasses register the magic-byte types they handle by calling
+    # `handles :type, ...` at class-body load time. The base class
+    # maintains the registry; new formats are added by creating a new
+    # subclass file with a `handles` declaration, with no edits to this
+    # file or to any branching logic.
     class Extractor
+      @@registry = {}
+
+      class << self
+        # Declare which magic-byte types this extractor handles.
+        # Called at class-body load time in each subclass.
+        def handles(*magic_types)
+          magic_types.each { |type| @@registry[type] = self }
+        end
+
+        # Resolve the extractor class for a magic-byte type, or nil if
+        # no extractor is registered. Triggers eager load of all
+        # extractor subclasses on first miss so every `handles`
+        # declaration has had a chance to fire.
+        def for_magic_type(type)
+          return @@registry[type] if @@registry.key?(type)
+
+          eager_load_subclasses!
+          @@registry[type]
+        end
+
+        # The full type → class registry. Exposed for introspection
+        # (specs, debugging). Not for mutation.
+        def registry
+          @@registry
+        end
+
+        def registered_types
+          @@registry.keys
+        end
+
+        # Force-load every autoloaded constant under Extractors so that
+        # each subclass's `handles` declaration runs. Idempotent.
+        def eager_load_subclasses!
+          Extractors.constants.each { |name| Extractors.const_get(name) }
+        end
+      end
+
       def initialize(archive)
         @archive = archive
       end
 
       def extract(_target)
-        raise NotImplementedError.new("You must implement this method")
+        raise NotImplementedError, "you must implement #extract"
+      end
+
+      private
+
+      # Detect inner format of decompressed data and extract it
+      # recursively, or write raw output when no extractor matches.
+      # Shared by GzipExtractor and XzExtractor.
+      def extract_inner(data, target)
+        inner_type = FileMagic.detect_bytes(data)
+        extractor_class = self.class.for_magic_type(inner_type) if inner_type
+
+        if extractor_class
+          temp = File.join(target, ".temp_#{Time.now.to_i}_#{rand(1000)}")
+          File.binwrite(temp, data)
+          extractor_class.new(temp).extract(target)
+        else
+          write_raw_output(data, target)
+        end
+      ensure
+        FileUtils.rm_f(temp) if temp
+      end
+
+      def write_raw_output(data, target)
+        basename = File.basename(@archive, ".*")
+        File.binwrite(File.join(target, basename), data)
       end
     end
   end

data/lib/excavate/extractors/gzip_extractor.rb

@@ -5,13 +5,11 @@ require "zlib"
 module Excavate
   module Extractors
     class GzipExtractor < Extractor
-      def extract(target)
-        basename = File.basename(@archive, ".*")
-        output_path = File.join(target, basename)
+      handles :gzip
 
-        Zlib::GzipReader.open(@archive) do |gz|
-          File.write(output_path, gz.read, mode: "wb")
-        end
+      def extract(target)
+        data = Zlib::GzipReader.open(@archive, &:read)
+        extract_inner(data, target)
       end
     end
   end

data/lib/excavate/extractors/ole_extractor.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "omnizip"
-require "omnizip/formats/ole"
-require_relative "../file_magic"
 
 module Excavate
   module Extractors
@@ -10,6 +8,8 @@ module Excavate
     #
     # Uses Omnizip's OLE format support for extraction.
     class OleExtractor < Extractor
+      handles :ole
+
       def extract(target)
         do_extract(target)
         rename_archives(target)

data/lib/excavate/extractors/rpm_extractor.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "omnizip"
-require "omnizip/formats/rpm"
 
 module Excavate
   module Extractors
@@ -10,6 +9,8 @@ module Excavate
     # Uses Omnizip's RPM format support for extraction.
     # Extracts the raw payload as a file (e.g., fonts.src.cpio.gz).
     class RpmExtractor < Extractor
+      handles :rpm
+
       def extract(target)
         rpm = Omnizip::Formats::Rpm::Reader.new(@archive)
         rpm.open

data/lib/excavate/extractors/seven_zip_extractor.rb

@@ -5,8 +5,9 @@ require "omnizip"
 module Excavate
   module Extractors
     class SevenZipExtractor < Extractor
+      handles :seven_zip, :exe
+
       def extract(target)
-        # Check for embedded 7z in self-extracting archives
         offset = Omnizip::Formats::SevenZip.search_embedded(@archive)
 
         if offset
@@ -15,7 +16,6 @@ module Excavate
             reader.extract_all(target)
           end
         else
-          # Regular 7z archive
           Omnizip::Formats::SevenZip.open(@archive) do |reader|
             reader.extract_all(target)
           end

data/lib/excavate/extractors/tar_extractor.rb

@@ -5,6 +5,8 @@ require "omnizip"
 module Excavate
   module Extractors
     class TarExtractor < Extractor
+      handles :tar
+
       def extract(target)
         reader = Omnizip::Formats::Tar::Reader.open(@archive)
         reader.extract_all(target)

data/lib/excavate/extractors/xar_extractor.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 require "omnizip"
-require "omnizip/formats/xar"
 
 module Excavate
   module Extractors
     class XarExtractor < Extractor
+      handles :xar
+
       def extract(target)
         Omnizip::Formats::Xar.extract(@archive, target)
         rename_payload(target)

data/lib/excavate/extractors/xz_extractor.rb

@@ -1,70 +1,15 @@
 # frozen_string_literal: true
 
 require "omnizip"
-require "zlib"
 
 module Excavate
   module Extractors
-    # Extractor for XZ compressed archives (both .xz and .tar.xz formats)
-    #
-    # This extractor handles:
-    # - Pure XZ compressed files (.xz)
-    # - Compound TAR+XZ archives (.tar.xz)
-    #
-    # Uses Omnizip for XZ decompression.
     class XzExtractor < Extractor
-      def extract(target)
-        if tar_xz?
-          extract_tar_xz(target)
-        else
-          extract_pure_xz(target)
-        end
-      end
-
-      private
-
-      def tar_xz?
-        @archive.end_with?(".tar.xz", ".txz")
-      end
-
-      def extract_tar_xz(target)
-        data = Omnizip::Formats::Xz.decompress(@archive)
-        data = strip_compression(data)
-        validate_tar!(data)
-
-        # Write tar file and extract
-        temp_tar = File.join(target, ".temp_#{Time.now.to_i}_#{rand(1000)}.tar")
-        File.binwrite(temp_tar, data)
-
-        TarExtractor.new(temp_tar).extract(target)
-      ensure
-        File.delete(temp_tar) if temp_tar && File.exist?(temp_tar)
-      end
-
-      def strip_compression(data)
-        if FileMagic.detect_bytes(data) == :gzip
-          return Zlib::GzipReader.new(StringIO.new(data)).read
-        end
-
-        data
-      end
-
-      def validate_tar!(data)
-        inner_type = FileMagic.detect_bytes(data)
-        return if inner_type == :tar
+      handles :xz
 
-        inner_type ||= "unknown format"
-
-        raise UnknownArchiveError,
-              "Expected tar inside #{@archive}, got #{inner_type}"
-      end
-
-      def extract_pure_xz(target)
-        # Decompress XZ
+      def extract(target)
         data = Omnizip::Formats::Xz.decompress(@archive)
-        basename = File.basename(@archive, ".*")
-        output_path = File.join(target, basename)
-        File.binwrite(output_path, data)
+        extract_inner(data, target)
       end
     end
   end

data/lib/excavate/extractors/zip_extractor.rb

@@ -5,6 +5,8 @@ require "omnizip"
 module Excavate
   module Extractors
     class ZipExtractor < Extractor
+      handles :zip
+
       def extract(target)
         reader = Omnizip::Formats::Zip::Reader.new(@archive)
         reader.read

data/lib/excavate/extractors.rb

@@ -1,11 +1,17 @@
-require_relative "extractors/extractor"
-require_relative "extractors/cab_extractor"
-require_relative "extractors/cpio_extractor"
-require_relative "extractors/gzip_extractor"
-require_relative "extractors/ole_extractor"
-require_relative "extractors/rpm_extractor"
-require_relative "extractors/seven_zip_extractor"
-require_relative "extractors/tar_extractor"
-require_relative "extractors/xar_extractor"
-require_relative "extractors/xz_extractor"
-require_relative "extractors/zip_extractor"
+# frozen_string_literal: true
+
+module Excavate
+  module Extractors
+    autoload :Extractor, "excavate/extractors/extractor"
+    autoload :CabExtractor, "excavate/extractors/cab_extractor"
+    autoload :CpioExtractor, "excavate/extractors/cpio_extractor"
+    autoload :GzipExtractor, "excavate/extractors/gzip_extractor"
+    autoload :OleExtractor, "excavate/extractors/ole_extractor"
+    autoload :RpmExtractor, "excavate/extractors/rpm_extractor"
+    autoload :SevenZipExtractor, "excavate/extractors/seven_zip_extractor"
+    autoload :TarExtractor, "excavate/extractors/tar_extractor"
+    autoload :XarExtractor, "excavate/extractors/xar_extractor"
+    autoload :XzExtractor, "excavate/extractors/xz_extractor"
+    autoload :ZipExtractor, "excavate/extractors/zip_extractor"
+  end
+end