omnizip 0.3.8 → 0.3.10

data/TODO.refactor/06-instance-variable-access.md

@@ -0,0 +1,69 @@
+# 06 — Remove `instance_variable_set` / `instance_variable_get`
+
+Priority: **high**.
+Status: TODO.
+
+## Rule
+
+> NEVER use `instance_variable_set` or `instance_variable_get`. Accessing
+> another object's instance variables breaks encapsulation. If you need
+> the data, add a public accessor or rethink the ownership.
+
+## Inventory (54 occurrences)
+
+### `instance_variable_set` (writers)
+
+| File:Line | What | Fix |
+|---|---|---|
+| `lib/omnizip/formats/rpm/lead.rb:53,66-73` | Sets 9 attrs from a parsed hash in a factory | Replace with ctor args |
+| `lib/omnizip/password/zip_crypto_strategy.rb:118` | `crc32.instance_variable_set(:@crc, crc)` | Add `Crc32#reset(crc)` public method |
+| `lib/omnizip/formats/iso/reader.rb:161` | Sets `@full_path` on a record | Add public writer or store externally |
+| `lib/omnizip/formats/xz_impl/block_decoder.rb:573-574,629-630` | Sets decoder state | Add public setters on LZMA2 decoder |
+| `lib/omnizip/algorithms/lzma/xz_utils_decoder.rb:434-435,448,450` | Sets decoder state | Promote to ctor / public setters |
+| `lib/omnizip/zip/file.rb:378,387,450` | Sets entry state | Add public setters |
+| `lib/omnizip/formats/seven_zip/writer.rb:65,178,196` | Sets writer state | Add public setters |
+
+### `instance_variable_get` (readers)
+
+| File:Line | What | Fix |
+|---|---|---|
+| `lib/omnizip/parity.rb:181,187` | Reads `@recovery_blocks`, `@file_list` from verifier | Add public readers |
+| `lib/omnizip/parallel/parallel_compressor.rb:317` | Reads `@entries` from writer | Add public reader |
+| `lib/omnizip/formats/lzma_alone.rb:152-156` | Reads decoder state (`@lc`, `@lp`, `@pb`, `@dict_size`, `@uncompressed_size`) | Add `Decoder#properties` Struct or public attr_readers |
+| `lib/omnizip/formats/lzip.rb:149-151` | Reads decoder state | Same pattern |
+| `lib/omnizip/formats/iso/reader.rb:180` | Reads `@full_path` | Use the public reader from above |
+| `lib/omnizip/formats/msi/string_pool.rb:89` | Reads `@stream_name_map` | Add public reader |
+| `lib/omnizip/formats/rar/compression/ppmd/encoder.rb:55` | Reads `@mem_size` from model | Add public reader |
+| `lib/omnizip/formats/ole/dirent.rb:157` | Reads `@name_lookup` from parent | Add public reader |
+| `lib/omnizip/formats/xz_impl/block_decoder.rb` | (covered above) | |
+
+## Plan
+
+For each hotspot:
+
+1. Add a `attr_reader` (or `attr_accessor` if mutation is legitimate) on
+   the target class for the ivar being accessed.
+2. Replace `obj.instance_variable_get(:@foo)` with `obj.foo`.
+3. For setters: either (a) add a public writer if mutation is part of the
+   API contract, or (b) refactor to pass the value through the
+   constructor, or (c) add a domain-named method (e.g.,
+   `crc.reset(value)` instead of writing `@crc`).
+
+For `lib/omnizip/formats/rpm/lead.rb` (worst offender, 9 ivars set in a
+factory): replace the factory with `Lead.new(lead_type:, magic:, ...)`.
+Use a Struct or a lutaml-model class.
+
+For decoder state introspection (lzma_alone.rb, lzip.rb,
+block_decoder.rb): define a `Decoder::Properties` Struct (or
+`Omnizip::Models::DecoderProperties`) and expose it via a single
+`decoder.properties` accessor.
+
+## Acceptance
+
+- `grep -rn "instance_variable_set\|instance_variable_get" lib/` returns
+  zero matches (or only well-documented exceptions).
+- All specs pass.
+
+## Files
+
+~21 files; see table above.

data/TODO.refactor/07-respond-to-replacement.md

@@ -0,0 +1,91 @@
+# 07 — Replace `respond_to?` with proper typing
+
+Priority: **medium**.
+Status: **partial — see Remaining Work**.
+
+## Rule
+
+> NEVER use `respond_to?` for type checking. Use `is_a?` for type checks,
+> or better yet, design the type hierarchy so the check isn't needed.
+
+## Done in this pass
+
+- Removed `opts.respond_to?(:"#{k}=")` from `parallel_compressor.rb` and
+  `parallel_extractor.rb` by adding `ParallelOptions#apply(hash)` with a
+  fixed setter whitelist.
+- Removed `format.respond_to?(:metadata)` from
+  `optimization_registry.rb` by relying on `Strategy.metadata` being
+  defined on the base class.
+
+## Remaining work
+
+109 `respond_to?` occurrences remain in `lib/`. They fall into these
+categories (sampled):
+
+### A. Duck-typed IO/String inputs (largest category)
+
+`input.respond_to?(:read)` / `output.respond_to?(:write)` in
+`formats/xz.rb`, `formats/lzma_alone.rb`, `formats/lzip.rb`,
+`formats/xz_impl/*.rb`, `pipe/*.rb`.
+
+**Fix:** introduce `Omnizip::IO::Source.for(input)` and
+`Omnizip::IO::Sink.for(output)` adapter methods in `lib/omnizip/io.rb`
+that wrap String / StringIO / File / Pathname behind a single API.
+Replace each `respond_to?`-guarded branch with a polymorphic call on the
+adapter.
+
+### B. Job-size duck typing
+
+`job.respond_to?(:size)` in `parallel/job_scheduler.rb` (6 occurrences).
+
+**Fix:** define `Parallel::Job` base with `#size` returning a default of
+1. Jobs that know their size override; others inherit the default. The
+scheduler stops needing to ask.
+
+### C. Entry-type duck typing
+
+`entry.respond_to?(:name)`, `entry.respond_to?(:path)`,
+`entry.respond_to?(:filename)`, `entry.respond_to?(:read)`,
+`entry.respond_to?(:get_input_stream)` in
+`extraction/selective_extractor.rb`, `parallel/parallel_extractor.rb`,
+`commands/archive_list_command.rb`, `pipe/stream_decompressor.rb`,
+`formats/rar/reader.rb`.
+
+**Fix:** define `Omnizip::Models::Entry` as a common base for
+zip/seven_zip/rar/tar entry classes. Each format's entry inherits and
+implements the contract (`#name`, `#size`, `#unix_perms`, `#mtime`,
+etc., returning nil when not applicable).
+
+### D. Platform feature detection
+
+`File.respond_to?(:symlink)`, `File.respond_to?(:link)`,
+`io.respond_to?(:pos)`, `io.respond_to?(:seek)` in `link_handler.rb`,
+`file_type.rb`.
+
+**Fix:** add `Platform.symlinks_supported?`,
+`Platform.seekable?(io)` predicates in `lib/omnizip/platform.rb`.
+
+### E. Hash-to-object metaprogramming
+
+`opts.respond_to?(:"#{k}=")` — same as ParallelOptions pattern. Fix
+case-by-case with whitelisted `apply(hash)` methods.
+
+### F. Reader-specific methods
+
+`reader.respond_to?(:split_reader)`,
+`elem.respond_to?(:text)`, `entry.respond_to?(:method)` — these are
+narrow cases. Convert to `is_a?` checks against the concrete class, or
+introduce a small type hierarchy.
+
+## Recommended execution order
+
+1. Tracks A and D — small, localized, no API change for callers.
+2. Track B — single file, base class addition.
+3. Track C — larger; needs the Entry base class first.
+4. Track E — case-by-case.
+5. Track F — case-by-case.
+
+## Acceptance
+
+`grep -rn "respond_to?" lib/` returns zero matches (or each remaining
+occurrence is annotated with `# allowed: <reason>`).

data/TODO.refactor/08-spec-doubles.md

@@ -0,0 +1,27 @@
+# 08 — Remove `double()` from specs
+
+Priority: **low** (1 occurrence).
+Status: TODO.
+
+## Rule
+
+> NEVER use `double()` in specs. Use real model instances or lightweight
+  Structs.
+
+## Inventory
+
+| File:Line | Code |
+|---|---|
+| `spec/omnizip/formats/rar/rar5/solid/solid_stream_spec.rb:41` | `stat = double("stat")` |
+
+## Plan
+
+1. Read the spec context to see which `File::Stat` interface the spec
+   exercises.
+2. Replace with `Struct.new(:mtime, :size, :mode, ...).new(...)` or
+   `File::Stat.new(real_path)` if a real file is available.
+
+## Acceptance
+
+- `grep -rn "double(" spec/` returns zero matches.
+- Spec passes.

data/TODO.refactor/09-cli-shared-module.md

@@ -0,0 +1,35 @@
+# 09 — CLI shared module
+
+Priority: **low**.
+Status: TODO.
+
+## Problem
+
+`handle_error` is duplicated verbatim in three Thor classes inside
+`lib/omnizip/cli.rb` (lines 81–84, 312–315, 557–560). `format_bytes`
+(line 562) is a utility that doesn't belong inside the CLI class.
+
+## Plan
+
+1. Create `lib/omnizip/cli/shared.rb` defining:
+   ```ruby
+   module Omnizip
+     class Cli
+       module Shared
+         def handle_error(err)
+           # ...
+         end
+         module_function :format_bytes
+       end
+     end
+   end
+   ```
+2. Each Thor class `include`s `Shared`.
+3. Move `format_bytes` out of the CLI class proper; place it in a
+   `Omnizip::Cli::Formatters` module (or under `Omnizip::Utils::Bytes` if
+   broader use exists).
+
+## Acceptance
+
+- Single definition of `handle_error` and `format_bytes`.
+- CLI specs pass.

data/TODO.refactor/10-format-detector-ocp.md

@@ -0,0 +1,34 @@
+# 10 — FormatDetector OCP
+
+Priority: **medium**.
+Status: TODO.
+
+## Problem
+
+`lib/omnizip/format_detector.rb:112-123` maps format symbols to reader
+classes via a `case` statement. Adding a new format requires modifying
+this method — a clear OCP violation. The `FormatRegistry` already
+registers each format handler; this case statement duplicates that
+knowledge.
+
+## Plan
+
+1. Replace the case statement with a lookup against `FormatRegistry`:
+   ```ruby
+   def reader_for(format)
+     FormatRegistry.get(format) ||
+       raise(UnsupportedFormatError, "No reader for #{format}")
+   end
+   ```
+2. Ensure every format that previously appeared in the case statement is
+   registered in `FormatRegistry` with its reader class.
+3. If a format is detected but its handler hasn't been required yet, the
+   registry lookup must trigger autoload — verify the autoload wiring in
+   `lib/omnizip.rb` makes this work.
+
+## Acceptance
+
+- `lib/omnizip/format_detector.rb` no longer has a format-specific case.
+- All format_detector specs pass.
+- A new format can be added by registering it, with zero edits to
+  FormatDetector.

data/TODO.refactor/11-convenience-decoupling.md

@@ -0,0 +1,38 @@
+# 11 — Convenience module decoupling
+
+Priority: **medium**.
+Status: TODO.
+
+## Problem
+
+`lib/omnizip/convenience.rb` (359 lines) hardcodes `Omnizip::Zip::File`
+in 7 method bodies (lines 45, 87, 112, 149, 175, 207, 227) —
+`compress_file`, `compress_directory`, `extract_archive`,
+`list_archive`, `read_from_archive`, `add_to_archive`,
+`remove_from_archive`. The codebase supports 7z, XZ, tar, gzip, bzip2,
+RAR, but convenience methods are ZIP-only.
+
+## Plan
+
+1. Add a `format:` keyword argument to each convenience method.
+   Default to `:zip` for backward compatibility.
+2. Resolve the format handler via `FormatRegistry.get(format)` and
+   delegate. If the handler doesn't expose the needed operation, raise a
+   clear `UnsupportedFormatError` describing what's missing.
+3. Each format handler (zip, seven_zip, tar, gzip, xz, bzip2) should
+   implement a shared `Handler` interface with `#add_file`,
+   `#add_directory`, `#extract`, `#list`, `#read`, `#remove`. This
+   becomes the contract for being usable from `convenience.rb`.
+
+## Acceptance
+
+- Convenience methods accept `format:` and dispatch via registry.
+- ZIP path remains the default with no behavior change.
+- At least one non-ZIP format (e.g., tar) is wired up end-to-end.
+
+## Scope note
+
+Full format handler interface extraction is large. This pass:
+1. Adds the `format:` keyword with ZIP default.
+2. Wires tar as a second supported format (simplest after zip).
+3. Leaves the remaining formats as documented future work.

data/TODO.refactor/12-thread-safety.md

@@ -0,0 +1,8 @@
+# 12 — Thread safety
+
+Priority: covered by track 01.
+Status: n/a.
+
+The `Registry` base class introduced in track 01 includes `Mutex`-based
+synchronization around mutations (`register`, `reset!`). All migrated
+registries inherit this for free. No standalone work.

data/TODO.refactor/13-lutaml-model-migration.md

@@ -0,0 +1,82 @@
+# 13 — lutaml-model migration
+
+Priority: **medium**.
+Status: TODO (large; this pass establishes the pattern, full migration
+is follow-up).
+
+## Rule
+
+> ALL (de)serialization goes through the framework. Declare attributes
+> with `attribute :name, :type`. Declare wire names with a `mapping do
+> ... end` block. Never write `def to_h` / `def from_h` / `def to_json`
+> / `def from_json` on a model class.
+
+## Inventory
+
+26 `def to_h` occurrences across 22 files. 2 `def to_json`. None use
+lutaml-model today even though the gemspec declares the dependency.
+
+### Models (lib/omnizip/models/)
+
+- `compression_options.rb` (`to_h`, `to_json`)
+- `algorithm_metadata.rb` (`to_h`, `to_json`)
+- `conversion_result.rb`
+- `eta_result.rb`
+- `filter_config.rb`
+- `match_result.rb`
+- `optimization_suggestion.rb`
+- `parallel_options.rb`
+- `performance_result.rb`
+- `profile_report.rb`
+- `progress_options.rb`
+- `conversion_options.rb`
+
+### Format entry/metadata classes
+
+- `formats/xar/entry.rb`
+- `formats/zip/unix_extra_field.rb`
+- `formats/rpm/header.rb`
+- `metadata/entry_metadata.rb`
+- `metadata/archive_metadata.rb`
+
+### Other
+
+- `progress/operation_progress.rb`
+- `profile/profile_registry.rb`, `custom_profile.rb`, `compression_profile.rb`
+- `link_handler/symbolic_link.rb`, `hard_link.rb`
+
+## Plan (this pass)
+
+1. Establish the pattern by migrating **two representative models**:
+   `Omnizip::Models::CompressionOptions` and
+   `Omnizip::Models::AlgorithmMetadata`. Convert to lutaml-model:
+   ```ruby
+   class CompressionOptions < Lutaml::Model::Serializable
+     attribute :algorithm, :string
+     attribute :level, :integer, default: 6
+     # ...
+     mapping do
+       map :algorithm, to: :algorithm
+       map :level, to: :level
+     end
+   end
+   ```
+   The framework provides `to_hash`, `to_json`, `from_hash`,
+   `from_json` automatically — remove the hand-rolled versions.
+
+2. Delete the manual `to_h` / `to_json` from those two files.
+
+3. Document the migration recipe in this TODO file for the remaining
+   models.
+
+## Acceptance
+
+- Two models migrated; their specs still pass.
+- `grep -rn "def to_h\|def to_json" lib/omnizip/models/` count drops by
+  at least 2.
+
+## Remaining work (future pass)
+
+Migrate the other ~24 files following the established recipe. The
+metadata/entry classes likely share structure and may collapse into a
+smaller set of richer models — review for MECE opportunities.

data/TODO.refactor/14-add-missing-specs.md

@@ -0,0 +1,25 @@
+# 14 — Add missing specs
+
+Priority: **high**.
+Status: TODO.
+
+## Plan
+
+Add or strengthen specs for:
+
+1. `Omnizip::Registry` (new base class from track 01) — register / get /
+   registered? / available / reset! / thread-safety smoke test / custom
+   not-found error.
+2. `Omnizip::Error` hierarchy (track 02) — confirm inheritance and
+   aliases.
+3. `Omnizip::Cli::Shared` (track 09) — `handle_error` and
+   `format_bytes`.
+4. `Omnizip::IO::Source` / `Omnizip::IO::Sink` (track 07) — adapter
+   behavior for String / StringIO / File / Pathname.
+5. Promoted public methods (track 05) — wherever a method moves from
+   private to public, ensure a spec covers its new visibility.
+
+## Acceptance
+
+- All new specs pass.
+- No `double()` introduced.

data/lib/omnizip/algorithm.rb

@@ -16,8 +16,6 @@
 # See the COPYING file for the complete text of the license.
 #
 
-require "omnizip/algorithm_registry"
-
 module Omnizip
   # Abstract base class for compression algorithms.
   #

data/lib/omnizip/algorithm_registry.rb

@@ -17,70 +17,42 @@
 #
 
 module Omnizip
-  # Registry for managing compression algorithm classes.
-  #
-  # This class provides a centralized registry for compression algorithms,
-  # allowing algorithms to self-register and be retrieved by name.
-  # It implements a plugin-style architecture for extensibility.
-  class AlgorithmRegistry
-    class << self
-      # Register an algorithm class with the registry.
-      #
-      # @param name [Symbol, String] The name identifier for the algorithm
-      # @param klass [Class] The algorithm class to register
-      # @raise [ArgumentError] If name or klass is nil
-      # @return [void]
-      def register(name, klass)
-        raise ArgumentError, "Algorithm name cannot be nil" if name.nil?
-        raise ArgumentError, "Algorithm class cannot be nil" if klass.nil?
-
-        algorithms[name.to_sym] = klass
-      end
-
-      # Retrieve an algorithm class by name.
-      #
-      # @param name [Symbol, String] The name identifier for the algorithm
-      # @raise [UnknownAlgorithmError] If algorithm is not registered
-      # @return [Class] The registered algorithm class
-      def get(name)
-        algorithm = algorithms[name.to_sym]
-        return algorithm if algorithm
-
-        raise UnknownAlgorithmError,
-              "Unknown algorithm: #{name}. " \
-              "Available: #{available.join(', ')}"
-      end
+  class AlgorithmRegistry < Omnizip::Registry
+    BUILTIN_ALGORITHMS = {
+      lzma: "Omnizip::Algorithms::LZMA",
+      lzma2: "Omnizip::Algorithms::LZMA2",
+      ppmd7: "Omnizip::Algorithms::PPMd7",
+      ppmd8: "Omnizip::Algorithms::PPMd8",
+      bzip2: "Omnizip::Algorithms::BZip2",
+      deflate: "Omnizip::Algorithms::Deflate",
+      deflate64: "Omnizip::Algorithms::Deflate64",
+      zstandard: "Omnizip::Algorithms::Zstandard",
+    }.freeze
 
-      # Check if an algorithm is registered.
-      #
-      # @param name [Symbol, String] The name identifier for the algorithm
-      # @return [Boolean] True if algorithm is registered, false otherwise
-      def registered?(name)
-        algorithms.key?(name.to_sym)
-      end
-
-      # Get list of all registered algorithm names.
-      #
-      # @return [Array<Symbol>] Array of registered algorithm names
-      def available
-        algorithms.keys
+    class << self
+      def not_found_error_class
+        Omnizip::UnknownAlgorithmError
       end
 
-      # Reset the registry (primarily for testing).
-      #
-      # @return [void]
-      def reset!
-        algorithms.clear
+      def label
+        "Algorithm"
       end
 
-      private
+      def register(name, klass)
+        raise ArgumentError, "Algorithm name cannot be nil" if name.nil?
+        raise ArgumentError, "Algorithm class cannot be nil" if klass.nil?
 
-      # Get or initialize the algorithms hash.
-      #
-      # @return [Hash] The algorithms registry
-      def algorithms
-        @algorithms ||= {}
+        super
       end
     end
   end
 end
+
+# Lazy triggers — explicitly re-register on each miss so the entry
+# survives reset!. Object.const_get alone doesn't re-run the file body
+# once the constant is loaded.
+Omnizip::AlgorithmRegistry::BUILTIN_ALGORITHMS.each do |name, const_path|
+  Omnizip::AlgorithmRegistry.register_lazy(name) do
+    Omnizip::AlgorithmRegistry.register(name, Object.const_get(const_path))
+  end
+end

data/lib/omnizip/algorithms/lzma/bit_model.rb

@@ -37,7 +37,7 @@ module Omnizip
         MAX_PROB = 1 << 11 # 4096
         BIT_MODEL_TOTAL = 0x800 # XZ Utils RC_BIT_MODEL_TOTAL = 2048
 
-        attr_reader :probability
+        attr_accessor :probability
 
         # Initialize a new bit probability model
         #

data/lib/omnizip/algorithms/lzma/dictionary.rb

@@ -6,7 +6,8 @@ module Omnizip
       # Circular buffer dictionary for LZMA sliding window
       # Ported from XZ Utils lzma_decoder.c
       class Dictionary
-        attr_reader :size, :position, :buffer
+        attr_accessor :position, :buffer
+        attr_reader :size
 
         def initialize(size)
           @size = size
@@ -59,8 +60,8 @@ module Omnizip
         # Clone dictionary
         def clone
           dict = Dictionary.new(@size)
-          dict.instance_variable_set(:@buffer, @buffer.dup)
-          dict.instance_variable_set(:@position, @position)
+          dict.buffer = @buffer.dup
+          dict.position = @position
           dict
         end
       end