excavate 1.0.3 → 1.1.1

data/lib/excavate/file_magic.rb

@@ -2,31 +2,48 @@
 
 module Excavate
   class FileMagic
-    # [offset, magic_bytes, type]
+    # A magic-byte signature: where in the file to look, what bytes to
+    # expect, and which type they identify.
+    Signature = Struct.new(:offset, :magic, :type)
+
     SIGNATURES = [
-      [0, "MSCF\x00\x00\x00\x00".b, :cab],
-      [0, "\xFD7zXZ\x00".b, :xz],
-      [0, "\x1F\x8B".b, :gzip],
-      [257, "ustar".b, :tar],
+      Signature.new(0,   "MSCF\x00\x00\x00\x00".b, :cab),
+      Signature.new(0,   "\xFD7zXZ\x00".b,         :xz),
+      Signature.new(0,   "\x1F\x8B".b,             :gzip),
+      Signature.new(257, "ustar".b,                :tar),
+      Signature.new(0,   "7z\xBC\xAF\x27\x1C".b,   :seven_zip),
+      Signature.new(0,   "PK\x03\x04".b,           :zip),
+      Signature.new(0,   "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b, :ole),
+      Signature.new(0,   "xar!".b,                 :xar),
+      Signature.new(0,   "\xED\xAB\xEE\xDB".b,     :rpm),
+      Signature.new(0,   "070707".b,               :cpio),
+      Signature.new(0,   "070701".b,               :cpio),
+      Signature.new(0,   "070702".b,               :cpio),
+      Signature.new(0,   "MZ".b,                   :exe),
     ].freeze
 
-    MAX_READ = SIGNATURES.map { |o, m, _| o + m.bytesize }.max
+    MAX_READ = SIGNATURES.map do |signature|
+      signature.offset + signature.magic.bytesize
+    end.max
 
     def self.detect(path)
-      beginning = File.read(path, MAX_READ, mode: "rb")
-      detect_bytes(beginning)
+      detect_bytes(File.read(path, MAX_READ, mode: "rb"))
     end
 
     def self.detect_bytes(data)
       return nil if data.nil? || data.empty?
 
-      SIGNATURES.each do |offset, magic, type|
-        next if data.bytesize < offset + magic.bytesize
+      matching_signature(data)&.type
+    end
+
+    def self.matching_signature(data)
+      SIGNATURES.find do |signature|
+        next if data.bytesize < signature.offset + signature.magic.bytesize
 
-        return type if data.byteslice(offset, magic.bytesize) == magic
+        slice = data.byteslice(signature.offset, signature.magic.bytesize)
+        slice == signature.magic
       end
-
-      nil
     end
+    private_class_method :matching_signature
   end
 end

data/lib/excavate/filesystem.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Excavate
+  # Filesystem helpers that absorb Windows file-locking quirks.
+  #
+  # On Windows, files and directories may be transiently locked by
+  # antivirus, indexing, or other processes immediately after they are
+  # written. Naive `FileUtils.rm` / `rm_rf` can raise `Errno::EACCES`
+  # or `Errno::ENOTEMPTY`. These helpers retry a small number of times
+  # before giving up, which is enough to ride out the brief lock
+  # windows seen in CI.
+  module Filesystem
+    module_function
+
+    RETRYABLE_ERRORS = [Errno::EACCES, Errno::ENOTEMPTY].freeze
+    DEFAULT_MAX_RETRIES = 5
+    DEFAULT_RETRY_DELAY = 0.2
+
+    def remove(path, max_retries: DEFAULT_MAX_RETRIES,
+               delay: DEFAULT_RETRY_DELAY)
+      with_retry(max_retries: max_retries, delay: delay) { FileUtils.rm(path) }
+    end
+
+    def remove_recursive(path, max_retries: DEFAULT_MAX_RETRIES,
+                         delay: DEFAULT_RETRY_DELAY)
+      with_retry(max_retries: max_retries, delay: delay) do
+        FileUtils.rm_rf(path)
+      end
+    end
+
+    # Replace +archive_path+ with the contents of +contents_dir+,
+    # absorbing Windows file-locking quirks. The optimistic path is
+    # delete-then-rename; if the target file is locked we degrade to
+    # copying each extracted file next to it so the user still has
+    # access to the data.
+    def replace_with_contents(archive_path, contents_dir)
+      remove(archive_path)
+      FileUtils.mv(contents_dir, archive_path)
+    rescue Errno::EACCES
+      scatter_contents(contents_dir, File.dirname(archive_path))
+    end
+
+    # Run +block+, retrying the documented retryable errno errors up
+    # to +max_retries+ times with +delay+ seconds between attempts.
+    def with_retry(max_retries: DEFAULT_MAX_RETRIES, delay: DEFAULT_RETRY_DELAY)
+      attempts = 0
+      begin
+        yield
+      rescue *RETRYABLE_ERRORS => e
+        attempts += 1
+        raise e if attempts >= max_retries
+
+        sleep(delay)
+        retry
+      end
+    end
+
+    # Copy each file from +source_dir+ into +destination_dir+, skipping
+    # any name that already exists. The degraded fallback used when an
+    # archive cannot be moved into place because it is locked.
+    def scatter_contents(source_dir, destination_dir)
+      Dir.glob(File.join(source_dir, "**", "*")).each do |src|
+        next unless File.file?(src)
+
+        dest = File.join(destination_dir, File.basename(src))
+        FileUtils.cp(src, dest) unless File.exist?(dest)
+      end
+    end
+  end
+end

data/lib/excavate/nested_cab_fallback.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Excavate
+  # Decides whether a failed extraction of a `:exe`-typed archive
+  # should be retried as a CAB.
+  #
+  # Some self-extracting EXEs produced by older Microsoft toolchains
+  # wrap a CAB rather than a 7z payload. When the 7z reader fails to
+  # parse one of these, it surfaces a small number of distinctive
+  # error strings. Rather than sniffing those strings inline inside
+  # Archive's rescue clause, the heuristic is named and tested here.
+  class NestedCabFallback
+    SIGNATURE_PHRASES = [
+      /\AInvalid file format/,
+      /\AUnrecognized archive format/,
+      /Invalid \.7z signature/,
+    ].freeze
+
+    class << self
+      def applies_to?(type, error)
+        type == :exe && phrase_match?(error.message)
+      end
+
+      private
+
+      def phrase_match?(message)
+        SIGNATURE_PHRASES.any? { |pattern| pattern.match?(message) }
+      end
+    end
+  end
+end

data/lib/excavate/selection.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Excavate
+  # Picks files from an extracted tree by either an explicit name list
+  # or a glob filter. Used by Archive's selective-extraction modes
+  # (extract particular files / extract by filter) to share the
+  # scaffolding that lives around the matching itself.
+  class Selection
+    def self.from_files(names)
+      new(file_names: names)
+    end
+
+    def self.from_filter(pattern)
+      new(filter: pattern)
+    end
+
+    def initialize(file_names: nil, filter: nil)
+      @file_names = file_names
+      @filter = filter
+    end
+
+    # Match +paths+ (absolute file paths produced by an extraction)
+    # against this selection. +base_dir+ is the prefix to strip when
+    # comparing names; matches are returned as absolute paths from
+    # +paths+. Raises TargetNotFoundError when nothing matches.
+    def match(paths, base_dir)
+      if @file_names
+        match_explicit(paths, base_dir)
+      else
+        match_filter(paths, base_dir)
+      end
+    end
+
+    private
+
+    def match_explicit(paths, base_dir)
+      @file_names.map do |target|
+        found = paths.find { |path| relative(path, base_dir) == target }
+        raise TargetNotFoundError, "File `#{target}` not found." unless found
+
+        found
+      end
+    end
+
+    def match_filter(paths, base_dir)
+      matched = paths.select do |path|
+        File.fnmatch?(@filter, relative(path, base_dir))
+      end
+      if matched.empty?
+        raise TargetNotFoundError,
+              "Filter `#{@filter}` matched no file."
+      end
+
+      matched
+    end
+
+    # Strip +base_dir+ prefix and any leading slash/backslash so that
+    # the result is an archive-relative path that can be compared
+    # against caller-supplied names or filters.
+    def relative(path, base_dir)
+      path.sub(base_dir, "").delete_prefix("/").delete_prefix("\\")
+    end
+  end
+end

data/lib/excavate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Excavate
-  VERSION = "1.0.3"
+  VERSION = "1.1.1"
 end

data/lib/excavate.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "excavate/version"
-require_relative "excavate/extractors"
-require_relative "excavate/archive"
-require_relative "excavate/file_magic"
-require_relative "excavate/utils"
+require "fileutils"
+require "tmpdir"
 
 module Excavate
   class Error < StandardError; end
@@ -17,3 +14,14 @@ module Excavate
 
   class UnknownArchiveError < Error; end
 end
+
+module Excavate
+  autoload :VERSION, "excavate/version"
+  autoload :FileMagic, "excavate/file_magic"
+  autoload :Filesystem, "excavate/filesystem"
+  autoload :Selection, "excavate/selection"
+  autoload :NestedCabFallback, "excavate/nested_cab_fallback"
+  autoload :Extractors, "excavate/extractors"
+  autoload :Archive, "excavate/archive"
+  autoload :CLI, "excavate/cli"
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: excavate
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.1
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-24 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cabriolet
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.9
+        version: 0.3.11
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.9
+        version: 0.3.11
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -73,6 +73,19 @@ files:
 - LICENSE.adoc
 - README.adoc
 - Rakefile
+- TODO.fixup/01-autoload-migration.md
+- TODO.fixup/02-redundant-external-requires.md
+- TODO.fixup/03-extractor-registry-ocp.md
+- TODO.fixup/04-filemagic-signature-struct.md
+- TODO.fixup/05-utils-silence-stream-dead-code.md
+- TODO.fixup/06-archive-filesystem-module.md
+- TODO.fixup/07-archive-targets-helper.md
+- TODO.fixup/08-archive-selection-dry.md
+- TODO.fixup/09-cab-fallback-heuristic-named.md
+- TODO.fixup/10-specs-remove-respond-to-matcher.md
+- TODO.fixup/11-specs-cover-new-collaborators.md
+- TODO.fixup/12-final-verification.md
+- TODO.fixup/README.md
 - docs/Gemfile
 - docs/_config.yml
 - docs/assets/logo.svg
@@ -165,7 +178,9 @@ files:
 - lib/excavate/extractors/xz_extractor.rb
 - lib/excavate/extractors/zip_extractor.rb
 - lib/excavate/file_magic.rb
-- lib/excavate/utils.rb
+- lib/excavate/filesystem.rb
+- lib/excavate/nested_cab_fallback.rb
+- lib/excavate/selection.rb
 - lib/excavate/version.rb
 homepage: https://github.com/omnizip/excavate
 licenses:

data/lib/excavate/utils.rb

@@ -1,14 +0,0 @@
-module Excavate
-  module Utils
-    module_function
-
-    def silence_stream(stream)
-      old_stream = stream.dup
-      stream.reopen(/mswin|mingw/.match?(RbConfig::CONFIG["host_os"]) ? File::NULL : File::NULL)
-      stream.sync = true
-      yield
-    ensure
-      stream.reopen(old_stream)
-    end
-  end
-end