excavate 1.0.3 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6360dbc5e452e6a0984a8bb8394051fa74da9d33700afd1ca9b36dbd73f9eeeb
-  data.tar.gz: 4d1f8e805be65dd56c6194915a43433561ba29572b016d6dc3d613617140957f
+  metadata.gz: b8c1a236bccd731f1a145805e3fe1288bb9536493331657ff0718e17be9f847b
+  data.tar.gz: c60465a7191a66dd237d4ae88e6dc631cd26c6be1e1f161f594358e4d1adcdce
 SHA512:
-  metadata.gz: dd1b31fabaf5c27c182bfec752255f918acf63763630bd7b6e39850f8296219b0ff182458efb3cfc5b3fe04f448b657a5e8b197330d532f1ccceed22e78a7ba3
-  data.tar.gz: f8a7aa72c8486144b9dcd09c5ecc05fa4c0acefbcc7482dca5a09cb1725d0d84438125438f1020dbdc478e37dce02486d1c4fdab7d37dc62e033a57f0094bd6b
+  metadata.gz: dda5395e5512553bd35c793c186042d5b64b5a72cec221d30dfad325966e88af3364c1470f7d2afbfa595e68dee90219ac0ce4279ac7301fb4efc400498ef1a8
+  data.tar.gz: 979eb4fe6b6af40579c9b80b77e92f5229117deca264fa2035a0cdd1dd5d28ece49d0c2082ee7fc7578439826424522c30c669e70f2f8ea468ed5ded88dce3b8

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-19 00:32:08 UTC using RuboCop version 1.85.1.
+# on 2026-07-24 04:23:45 UTC using RuboCop version 1.85.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,7 +11,7 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'excavate.gemspec'
 
-# Offense count: 21
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -20,77 +20,12 @@ Layout/LineLength:
     - 'bin/rspec'
     - 'excavate.gemspec'
     - 'lib/excavate/extractors/rpm_extractor.rb'
-    - 'lib/excavate/utils.rb'
     - 'spec/excavate/archive_spec.rb'
-    - 'test_archives/memory_test.rb'
-    - 'test_msi_memory.rb'
 
-# Offense count: 1
-# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
-Lint/DuplicateBranch:
-  Exclude:
-    - 'lib/excavate/utils.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Lint/ScriptPermission:
-  Exclude:
-    - 'test_archives/memory_test.rb'
-    - 'test_msi_memory.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: IgnoreEmptyBlocks, AllowUnusedKeywordArguments.
-Lint/UnusedBlockArgument:
-  Exclude:
-    - 'test_msi_memory.rb'
-
-# Offense count: 4
-# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
-Metrics/AbcSize:
-  Exclude:
-    - 'test_archives/memory_test.rb'
-    - 'test_msi_memory.rb'
-
-# Offense count: 2
-# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
-Metrics/CyclomaticComplexity:
-  Exclude:
-    - 'test_archives/memory_test.rb'
-    - 'test_msi_memory.rb'
-
-# Offense count: 11
+# Offense count: 5
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 82
-
-# Offense count: 2
-# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
-Metrics/PerceivedComplexity:
-  Exclude:
-    - 'test_archives/memory_test.rb'
-    - 'test_msi_memory.rb'
-
-# Offense count: 2
-# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
-# AllowedMethods: call
-# WaywardPredicates: infinite?, nonzero?
-Naming/PredicateMethod:
-  Exclude:
-    - 'test_archives/memory_test.rb'
-    - 'test_msi_memory.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Performance/RegexpMatch:
-  Exclude:
-    - 'test_archives/memory_test.rb'
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Performance/StringInclude:
-  Exclude:
-    - 'test_archives/memory_test.rb'
+  Max: 11
 
 # Offense count: 46
 # Configuration parameters: Prefixes, AllowedPatterns.
@@ -101,12 +36,12 @@ RSpec/ContextWording:
     - 'spec/excavate/cli_spec.rb'
     - 'spec/support/fresh_work_dir.rb'
 
-# Offense count: 11
+# Offense count: 18
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 16
 
-# Offense count: 18
+# Offense count: 32
 RSpec/MultipleExpectations:
   Max: 2
 
@@ -114,26 +49,3 @@ RSpec/MultipleExpectations:
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
-
-# Offense count: 8
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: trailing_conditional, ternary
-Style/EmptyStringInsideInterpolation:
-  Exclude:
-    - 'test_archives/memory_test.rb'
-    - 'test_msi_memory.rb'
-
-# Offense count: 2
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Style/IdenticalConditionalBranches:
-  Exclude:
-    - 'lib/excavate/utils.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: implicit, explicit
-Style/RescueStandardError:
-  Exclude:
-    - 'test_msi_memory.rb'

data/TODO.fixup/01-autoload-migration.md

@@ -0,0 +1,65 @@
+# 01 — Autoload migration
+
+Status: **pending**
+
+## Why
+
+User's global rule:
+
+> NEVER use `require_relative` for internal library code. Never use `require`
+> with a path to code within your own library. Use Ruby `autoload` instead.
+> Define autoload entries in the immediate parent namespace's file — create
+> that file if it doesn't exist.
+
+Currently `lib/excavate.rb` and `lib/excavate/extractors.rb` eagerly pull in
+every file with `require_relative`, defeating lazy loading and creating
+implicit load-order couplings.
+
+## Scope
+
+Offending `require_relative` calls inside `lib/`:
+
+```
+lib/excavate.rb:3  require_relative "excavate/version"
+lib/excavate.rb:4  require_relative "excavate/extractors"
+lib/excavate.rb:5  require_relative "excavate/archive"
+lib/excavate.rb:6  require_relative "excavate/file_magic"
+lib/excavate.rb:7  require_relative "excavate/utils"
+lib/excavate/cli.rb:3          require_relative "../excavate"
+lib/excavate/extractors.rb:1   require_relative "extractors/extractor"
+lib/excavate/extractors.rb:2   require_relative "extractors/cab_extractor"
+lib/excavate/extractors.rb:3   require_relative "extractors/cpio_extractor"
+lib/excavate/extractors.rb:4   require_relative "extractors/gzip_extractor"
+lib/excavate/extractors.rb:5   require_relative "extractors/ole_extractor"
+lib/excavate/extractors.rb:6   require_relative "extractors/rpm_extractor"
+lib/excavate/extractors.rb:7   require_relative "extractors/seven_zip_extractor"
+lib/excavate/extractors.rb:8   require_relative "extractors/tar_extractor"
+lib/excavate/extractors.rb:9   require_relative "extractors/xar_extractor"
+lib/excavate/extractors.rb:10  require_relative "extractors/xz_extractor"
+lib/excavate/extractors.rb:11  require_relative "extractors/zip_extractor"
+lib/excavate/extractors/ole_extractor.rb:5  require_relative "../file_magic"
+```
+
+## Plan
+
+1. `lib/excavate.rb` — the immediate-parent file for `Excavate::*`. Move
+   error classes to `lib/excavate/errors.rb` and autoload it. Autoload
+   `Archive`, `FileMagic`, `Utils`, `CLI`, `Extractors`. Keep
+   `Excavate::VERSION` autoloaded too.
+2. `lib/excavate/extractors.rb` — the immediate-parent file for
+   `Excavate::Extractors::*`. Replace all 11 `require_relative` lines with
+   `autoload` declarations.
+3. `lib/excavate/cli.rb` — drop the `require_relative "../excavate"`. CLI is
+   now autoloaded by the parent; the `thor` external require stays.
+4. `lib/excavate/extractors/ole_extractor.rb` — drop the
+   `require_relative "../file_magic"`. `FileMagic` is reachable via the
+   autoload chain `Excavate → FileMagic`.
+5. Create `lib/excavate/errors.rb` hosting the error hierarchy; have
+   `excavate.rb` autoload it eagerly so exception classes are always
+   defined for rescue clauses.
+
+## Acceptance
+
+- `grep -rn "require_relative" lib/` returns zero hits.
+- `bundle exec rspec` is green.
+- Loading the gem remains a single `require "excavate"` (Bundler-friendly).

data/TODO.fixup/02-redundant-external-requires.md

@@ -0,0 +1,48 @@
+# 02 — Drop redundant external requires
+
+Status: **pending**
+
+## Why
+
+`omnizip` itself uses `autoload` for every `Formats::*` constant (see
+`omnizip/formats.rb`). The per-format `require "omnizip/formats/cpio"` (and
+siblings) in our extractors are redundant — they re-trigger the same autoload
+resolution.
+
+Additionally the currently-staged (uncommitted) change to
+`cpio_extractor.rb` adds a second external require line:
+`require "omnizip"` followed by `require "omnizip/formats/cpio"`. Only one is
+needed.
+
+## Scope
+
+Files with redundant per-format requires:
+
+```
+lib/excavate/extractors/cpio_extractor.rb:3-4  require "omnizip" / require "omnizip/formats/cpio"
+lib/excavate/extractors/ole_extractor.rb:3-4   require "omnizip" / require "omnizip/formats/ole"
+lib/excavate/extractors/rpm_extractor.rb:3-4   require "omnizip" / require "omnizip/formats/rpm"
+lib/excavate/extractors/xar_extractor.rb:3-4   require "omnizip" / require "omnizip/formats/xar"
+lib/excavate/extractors/seven_zip_extractor.rb:3  require "omnizip"
+lib/excavate/extractors/tar_extractor.rb:3        require "omnizip"
+lib/excavate/extractors/xz_extractor.rb:3         require "omnizip"
+lib/excavate/extractors/zip_extractor.rb:3        require "omnizip"
+```
+
+## Plan
+
+Keep one `require "omnizip"` per file that touches an Omnizip constant.
+Delete the per-format `require "omnizip/formats/X"` lines — the autoload in
+`omnizip/formats.rb` resolves them on first reference. The staged
+`require "omnizip"` addition in cpio_extractor.rb becomes the single
+omnizip require for that file (replacing the redundant format require).
+
+For extractors that only touch a single Omnizip format constant, the
+`require "omnizip"` line is also technically unneeded if any other loaded
+file already requires omnizip — but keeping it makes each file
+independently loadable, which is good practice. Keep them.
+
+## Acceptance
+
+- No `require "omnizip/formats/..."` remains in `lib/`.
+- `bundle exec rspec` is green.

data/TODO.fixup/03-extractor-registry-ocp.md

@@ -0,0 +1,150 @@
+# 03 — Open/closed Extractor registry
+
+Status: **pending**
+
+## Why
+
+`Excavate::Extractors::Extractor.for_magic_type` currently consults a frozen
+`MAGIC_MAP` keyed by symbol → class-name-string and resolves via
+`const_get`. Adding a new extractor requires editing this hash. That
+violates OCP: the base class is open for *modification*, not just extension.
+
+The current spec even hard-codes the expected key list
+(`spec/excavate/extractors/extractor_spec.rb:6`), which means every new
+extractor needs edits in three places: the new file, the parent
+`extractors.rb`, and `MAGIC_MAP`. After this refactor only the new file
+needs to change.
+
+## Plan
+
+Replace the hash + const_get with a registry pattern:
+
+```ruby
+class Extractor
+  @registry = {}
+
+  class << self
+  private :inherited  # keep the hook itself private — registration is the API
+
+  def inherited(subclass)
+    super
+    subclass.instance_variable_set(:@handled_types, [])
+  end
+
+  def handles(*types)
+    @handled_types.concat(types)
+    Extractor.register(self, types)
+  end
+  end
+
+  def self.register(klass, types)
+    types.each { |t| registry[t] = klass }
+  end
+
+  def self.for_magic_type(type)
+    registry[type]
+  end
+
+  def self.registry
+    @registry
+  end
+end
+```
+
+Wait — the user forbids `instance_variable_set`. Use a different shape:
+
+```ruby
+class Extractor
+  @registry = {}
+
+  class << self
+    attr_reader :registry
+
+    def handles(*types)
+      types.each { |t| registry[t] = self }
+    end
+
+    def for_magic_type(type)
+      registry[type]
+    end
+
+    def inherited(subclass)
+      super
+      subclass.instance_variable_set(:@handled_types, [])  # FORBIDDEN
+    end
+  end
+end
+```
+
+Final design — no instance_variable_* and no const_get. Each subclass calls
+`handles :cab` at class-body load time, which writes itself into the
+parent's registry hash. The `inherited` hook is not needed because
+registration is explicit at class definition.
+
+```ruby
+# extractors/extractor.rb
+module Excavate
+  module Extractors
+    class Extractor
+      class << self
+        # Public registry API. Each subclass declares the magic types it
+        # handles via `handles :type, ...` at class-body load time.
+        def handles(*magic_types)
+          magic_types.each { |t| registry[t] = self }
+        end
+
+        def for_magic_type(type)
+          registry[type]
+        end
+
+        def registry
+          @registry ||= {}
+        end
+      end
+
+      def initialize(archive)
+        @archive = archive
+      end
+
+      def extract(_target)
+        raise NotImplementedError, "you must implement #extract"
+      end
+
+      private
+
+      def extract_inner(data, target) ... end
+      def write_raw_output(data, target) ... end
+    end
+  end
+end
+```
+
+Each subclass:
+
+```ruby
+class CabExtractor < Extractor
+  handles :cab
+  ...
+end
+
+class SevenZipExtractor < Extractor
+  handles :seven_zip, :exe
+  ...
+end
+```
+
+## Spec impact
+
+- Remove `MAGIC_MAP` frozen spec — the registry hash is no longer public.
+- Replace the per-type expectation loop with a "registered" check using
+  `Extractor.for_magic_type(...)`.
+- The "is registered for :type" specs in each extractor_spec.rb still pass
+  unchanged because they assert via `for_magic_type`.
+
+## Acceptance
+
+- Adding a new format requires only: new file under
+  `lib/excavate/extractors/`, new autoload entry in
+  `lib/excavate/extractors.rb`, `handles :foo` in the class body.
+- No edits to any other file.
+- All 185 specs pass (after extractor_spec is updated to drop MAGIC_MAP).

data/TODO.fixup/04-filemagic-signature-struct.md

@@ -0,0 +1,68 @@
+# 04 — FileMagic::Signature value object
+
+Status: **pending**
+
+## Why
+
+`FileMagic::SIGNATURES` is an array of `[offset, magic, type]` tuples.
+Reading call sites like `SIGNATURES.map { |o, m, _| o + m.bytesize }` or
+`SIGNATURES.each do |offset, magic, type|` requires the reader to memorise
+the positional convention. A named value object removes that cognitive load
+and documents intent.
+
+## Plan
+
+Introduce `FileMagic::Signature = Struct.new(:offset, :magic, :type)` and
+rewrite SIGNATURES as a list of `Signature.new(...)` literals. Update
+`detect_bytes` and `MAX_READ` to use field names.
+
+Sketch:
+
+```ruby
+module Excavate
+  class FileMagic
+    Signature = Struct.new(:offset, :magic, :type)
+
+    SIGNATURES = [
+      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 { |s| s.offset + s.magic.bytesize }.max
+
+    def self.detect(path)
+      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 |signature|
+        next if data.bytesize < signature.offset + signature.magic.bytesize
+
+        return signature.type if data.byteslice(signature.offset, signature.magic.bytesize) == signature.magic
+      end
+
+      nil
+    end
+  end
+end
+```
+
+`Signature` is internal to FileMagic so no autoload entry needed.
+
+## Acceptance
+
+- All file_magic_spec examples pass unchanged.
+- No positional-destructuring of signature tuples remains.

data/TODO.fixup/05-utils-silence-stream-dead-code.md

@@ -0,0 +1,57 @@
+# 05 — Clean up `Utils.silence_stream` dead branch
+
+Status: **pending**
+
+## Why
+
+Current implementation:
+
+```ruby
+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
+```
+
+Both arms of the ternary return `File::NULL`, so the OS-detection branch
+is dead code. RuboCop already flags it as `Lint/DuplicateBranch` and
+`Style/IdenticalConditionalBranches` in `.rubocop_todo.yml`.
+
+Also: `RbConfig` is referenced without `require "rbconfig"`. It happens to
+work because Ruby preloads it, but explicit is better.
+
+## Plan
+
+Two acceptable resolutions:
+
+**Option A** — delete the ternary entirely:
+
+```ruby
+def silence_stream(stream)
+  old_stream = stream.dup
+  stream.reopen(File::NULL)
+  stream.sync = true
+  yield
+ensure
+  stream.reopen(old_stream)
+end
+```
+
+**Option B** — delete the whole `Utils` module. Its only caller is
+`spec/excavate/cli_spec.rb` which uses it to swallow `$stdout` during CLI
+tests. That could be replaced with RSpec's `output(...).to_stdout` matcher
+(which is already used elsewhere in the same file) — but the silence_stream
+approach is more robust when the test doesn't care about the message body.
+
+Choose **Option A** — keep the helper, just remove the dead code.
+
+## Acceptance
+
+- `Utils.silence_stream` no longer has identical branches.
+- `Lint/DuplicateBranch` and `Style/IdenticalConditionalBranches` can be
+  removed from `.rubocop_todo.yml`.
+- cli_spec continues to silence $stdout.

data/TODO.fixup/06-archive-filesystem-module.md

@@ -0,0 +1,72 @@
+# 06 — Extract `Excavate::Filesystem` helper
+
+Status: **pending**
+
+## Why
+
+`Excavate::Archive` currently owns four Windows-safe retry helpers
+(`windows_safe_rm`, `windows_safe_rm_rf`, plus the inline
+`replace_archive_with_contents` rescue logic). These are pure
+filesystem operations with retry-on-`EACCES`/`ENOTEMPTY` semantics and
+have nothing to do with archives. They violate MECE: the Archive class
+is mixing archive orchestration with low-level FS reliability.
+
+## Plan
+
+Create `lib/excavate/filesystem.rb`:
+
+```ruby
+module Excavate
+  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) { FileUtils.rm_rf(path) }
+    end
+
+    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
+  end
+end
+```
+
+Update `lib/excavate.rb` to autoload `:Filesystem,
+"excavate/filesystem"`.
+
+Update `lib/excavate/archive.rb`:
+
+- `windows_safe_rm(path, ...)` → `Filesystem.remove(path)`
+- `windows_safe_rm_rf(path, ...)` → `Filesystem.remove_recursive(path)`
+- The `ensure ... FileUtils.rm_rf(target)` clauses in
+  `extract_particular_files` and `extract_by_filter` should also use
+  `Filesystem.remove_recursive` for consistency.
+- `replace_archive_with_contents` already rescues Errno::EACCES for a
+  *different* reason (Windows file lock during mv); leave it but route
+  the `windows_safe_rm(archive)` call through `Filesystem.remove`.
+
+## Acceptance
+
+- Archive no longer has private `windows_safe_*` methods.
+- New file `lib/excavate/filesystem.rb` exists with autoload.
+- All archive specs still pass.
+- New spec `spec/excavate/filesystem_spec.rb` covers both methods'
+  happy path and retry behaviour (use a fake error class with a stub
+  that fails N-1 times then succeeds).

data/TODO.fixup/07-archive-targets-helper.md

@@ -0,0 +1,62 @@
+# 07 — Extract `Excavate::Targets` helper
+
+Status: **pending**
+
+## Why
+
+`Excavate::Archive` owns three target-path safety helpers
+(`ensure_not_exist`, `ensure_empty`, `default_target`). They are pure
+path policy with no archive context — they belong in a focused value
+object so they can be tested in isolation and reused.
+
+## Plan
+
+Create `lib/excavate/targets.rb`:
+
+```ruby
+module Excavate
+  module Targets
+    module_function
+
+    def ensure_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_empty(path)
+      return if Dir.empty?(path)
+
+      raise TargetNotEmptyError,
+            "Target directory `#{File.basename(path)}` is not empty."
+    end
+
+    def default_for(source)
+      target = File.expand_path(File.basename(source, ".*"))
+      ensure_absent(target)
+      FileUtils.mkdir(target)
+      target
+    end
+  end
+end
+```
+
+Update `lib/excavate.rb` to autoload `:Targets, "excavate/targets"`.
+
+Update `lib/excavate/archive.rb`:
+
+- `ensure_not_exist(path)` → `Targets.ensure_absent(path)`
+- `ensure_empty(path)` → `Targets.ensure_empty(path)`
+- `default_target(source)` → `Targets.default_for(source)`
+
+Remove the now-empty private helpers.
+
+## Acceptance
+
+- Archive no longer has private target-safety methods.
+- New file `lib/excavate/targets.rb` with autoload.
+- New spec `spec/excavate/targets_spec.rb` covers all three methods
+  including the error paths.
+- Existing archive + cli specs still pass.