omnizip 0.3.9 → 0.3.10

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/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

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

@@ -52,6 +52,8 @@ module Omnizip
       #   result = decoder.decode_stream
       #
       class LzipDecoder
+        attr_reader :version, :dict_size, :member_size
+
         # Lzip magic bytes: "LZIP" in ASCII
         # Reference: lzip_decoder.c:106
         MAGIC = [0x4C, 0x5A, 0x49, 0x50].freeze

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

@@ -33,7 +33,7 @@ module Omnizip
       # extract the original bit values. It maintains a code value
       # that represents the current position within the range.
       class RangeDecoder < RangeCoder
-        attr_reader :code, :init_bytes_remaining
+        attr_reader :code, :init_bytes_remaining, :range, :stream
 
         # Initialize the range decoder
         #

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

@@ -86,7 +86,8 @@ module Omnizip
       RangeDecoder = LZMA::RangeDecoder
       SdkStateMachine = Implementations::SevenZip::LZMA::StateMachine
 
-      attr_reader :lc, :lp, :pb, :dict_size, :uncompressed_size
+      attr_reader :lc, :lp, :pb, :dict_size, :uncompressed_size,
+                  :range_decoder
 
       # XZ Utils dictionary constants (from lz_decoder.h)
       # See: /Users/mulgogi/src/external/xz/src/liblzma/lz/lz_decoder.h
@@ -431,8 +432,8 @@ check_rc_finished: true)
           #
           # If EOPM was NOT encountered (code != 0), leftover data is expected
           # (it's part of the compressed stream that we haven't read yet).
-          if @allow_eopm && @range_decoder&.code&.zero? && @range_decoder.instance_variable_get(:@stream)
-            stream = @range_decoder.instance_variable_get(:@stream)
+          if @allow_eopm && @range_decoder&.code&.zero? && @range_decoder&.stream
+            stream = @range_decoder.stream
             # Try to peek at the next byte - if available, there's data AFTER EOPM
             begin
               next_byte = stream.getbyte
@@ -445,9 +446,9 @@ check_rc_finished: true)
             rescue IOError, EOFError
               # Stream doesn't support peeking or is exhausted, that's fine
             end
-          elsif !@allow_eopm && @range_decoder&.instance_variable_get(:@stream)
+          elsif !@allow_eopm && @range_decoder&.stream
             # For LZMA2 mode (EOPM not allowed): check for leftover data
-            stream = @range_decoder.instance_variable_get(:@stream)
+            stream = @range_decoder.stream
             begin
               next_byte = stream.getbyte
               if next_byte

data/lib/omnizip/algorithms/lzma2/encoder.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "omnizip/algorithms"
-
 module Omnizip
   module Algorithms
     # LZMA2 encoder - delegates to XzLZMA2Encoder

data/lib/omnizip/algorithms/lzma2/lzma2_chunk.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "omnizip/algorithms"
-
 module Omnizip
   module Algorithms
     class LZMA2 < Algorithm

data/lib/omnizip/algorithms/lzma2/properties.rb

@@ -20,8 +20,6 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
-require "omnizip/algorithms"
-
 module Omnizip
   module Algorithms
     class LZMA2

data/lib/omnizip/algorithms/ppmd7/model.rb

@@ -36,7 +36,7 @@ module Omnizip
       class Model
         include Constants
 
-        attr_reader :max_order, :root_context, :current_context
+        attr_reader :max_order, :root_context, :current_context, :mem_size
 
         # Initialize the PPMd7 model
         #

data/lib/omnizip/algorithms/ppmd8/context.rb

@@ -2,8 +2,6 @@
 
 # Copyright (C) 2025 Ribose Inc.
 
-require "omnizip/algorithms/ppmd7/context"
-
 module Omnizip
   module Algorithms
     class PPMd8 < PPMdBase

data/lib/omnizip/algorithms/ppmd8/model.rb

@@ -35,7 +35,7 @@ module Omnizip
         include Constants
 
         attr_reader :max_order, :root_context, :current_context,
-                    :restoration_method, :run_length, :glue_count
+                    :restoration_method, :run_length, :glue_count, :mem_size
         attr_accessor :order_fall, :prev_success
 
         # Initialize the PPMd8 model

data/lib/omnizip/algorithms/ppmd8.rb

@@ -20,8 +20,6 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
-require "omnizip/algorithms"
-
 module Omnizip
   module Algorithms
     # PPMd8 (PPMdI) compression algorithm

data/lib/omnizip/algorithms/ppmd_base.rb

@@ -20,8 +20,6 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
-require "omnizip/algorithm"
-
 module Omnizip
   module Algorithms
     # Base class for PPMd (Prediction by Partial Matching) algorithms

data/lib/omnizip/algorithms/sevenzip_lzma2.rb

@@ -20,11 +20,6 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
-require "omnizip/algorithm"
-require "omnizip/models/algorithm_metadata"
-require "omnizip/algorithms/lzma2/encoder"
-require "omnizip/algorithms/lzma2/decoder"
-
 module Omnizip
   module Algorithms
     # 7-Zip LZMA2 compression algorithm.

data/lib/omnizip/algorithms/xz_lzma2.rb

@@ -20,11 +20,6 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
-require "omnizip/algorithm"
-require "omnizip/models/algorithm_metadata"
-require "omnizip/implementations/xz_utils/lzma2/encoder"
-require "omnizip/implementations/xz_utils/lzma2/decoder"
-
 module Omnizip
   module Algorithms
     # XZ Utils LZMA2 compression algorithm.

data/lib/omnizip/algorithms/zstandard/frame/header.rb

@@ -69,15 +69,15 @@ module Omnizip
 
             # Parse optional fields based on descriptor bits
             if header.window_descriptor?
-              header.send(:parse_window_descriptor, input)
+              header.parse_window_descriptor(input)
             end
 
             if header.dictionary_id?
-              header.send(:parse_dictionary_id, input)
+              header.parse_dictionary_id(input)
             end
 
             if header.content_size?
-              header.send(:parse_content_size, input)
+              header.parse_content_size(input)
             end
 
             header
@@ -174,8 +174,6 @@ module Omnizip
             (1 << @window_log) + (mantissa << (@window_log - 4))
           end
 
-          private
-
           # Parse window descriptor byte
           def parse_window_descriptor(input)
             byte = input.read(1).ord

data/lib/omnizip/algorithms.rb

@@ -3,6 +3,7 @@
 module Omnizip
   # Compression algorithm implementations
   module Algorithms
+    autoload :PPMdBase, "omnizip/algorithms/ppmd_base"
     autoload :LZMA2Const, "omnizip/algorithms/lzma2/constants"
     autoload :LZMA, "omnizip/algorithms/lzma"
     autoload :LZMA2, "omnizip/algorithms/lzma2"

data/lib/omnizip/archive_handler.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Omnizip
+  # Unified archive handler interface for the Convenience module.
+  #
+  # Each format that wants to participate in Omnizip.compress_file /
+  # extract_archive / etc. registers a Handler here. The Handler exposes
+  # a small canonical API (+create+, +open+, +extract_to+, +list+) that
+  # the Convenience module calls; the Handler then delegates to the
+  # format-specific reader/writer.
+  #
+  # @example Register a format
+  #   Omnizip::ArchiveHandler.register(:tar, TarHandler.new)
+  #
+  # @example Use from a caller
+  #   Omnizip::ArchiveHandler.for(:tar).create(path) { |w| w.add_file(...) }
+  module ArchiveHandler
+    @handlers = {}
+
+    class << self
+      # Register a handler for a format symbol.
+      #
+      # @param format [Symbol] e.g. +:zip+, +:tar+
+      # @param handler [Object] responding to the Handler interface
+      # @return [void]
+      def register(format, handler)
+        @handlers[format.to_sym] = handler
+      end
+
+      # Look up the handler for +format+. Triggers the registered lazy
+      # load constant if the format is one of the built-ins.
+      #
+      # @param format [Symbol]
+      # @return [Object]
+      # @raise [Omnizip::UnsupportedFormatError] if +format+ is unknown
+      def for(format)
+        handler = @handlers[format.to_sym]
+        return handler if handler
+
+        trigger = LAZY_LOAD_TRIGGERS[format.to_sym]
+        if trigger
+          trigger.call
+          handler = @handlers[format.to_sym]
+          return handler if handler
+        end
+
+        raise Omnizip::UnsupportedFormatError,
+              "No archive handler registered for #{format.inspect}. " \
+              "Registered: #{@handlers.keys.join(', ')}"
+      end
+
+      # List of registered format names.
+      #
+      # @return [Array<Symbol>]
+      def available
+        @handlers.keys
+      end
+
+      # Remove a handler (primarily for testing).
+      #
+      # @return [void]
+      def unregister(format)
+        @handlers.delete(format.to_sym)
+      end
+    end
+
+    # Lazy triggers — referencing the constant autoloads the handler's
+    # file, which then self-registers at the bottom of the file.
+    LAZY_LOAD_TRIGGERS = {
+      zip: -> { Omnizip::ArchiveHandlers::ZipHandler },
+      tar: -> { Omnizip::ArchiveHandlers::TarHandler },
+    }.freeze
+    private_constant :LAZY_LOAD_TRIGGERS
+  end
+end

data/lib/omnizip/archive_handlers/tar_handler.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module ArchiveHandlers
+    # Adapter that exposes the canonical +create+/+open+/+extract_to+
+    # /+list+ interface for the TAR format. Wraps +Omnizip::Formats::Tar+.
+    class TarHandler
+      def create(path, &block)
+        Omnizip::Formats::Tar.create(path, &block)
+      end
+
+      def open(path, &block)
+        Omnizip::Formats::Tar.open(path, &block)
+      end
+
+      def extract_to(path, output_dir, **_)
+        Omnizip::Formats::Tar.extract(path, output_dir)
+      end
+
+      def list(path, details: false, **_)
+        entries = Omnizip::Formats::Tar.list(path)
+        if details
+          entries.map do |entry|
+            {
+              name: entry.name,
+              size: entry.size,
+              directory: entry.directory?,
+              mtime: entry.mtime,
+              mode: entry.mode,
+            }
+          end
+        else
+          entries.map(&:name)
+        end
+      end
+
+      def read_entry(path, entry_name)
+        data = nil
+        Omnizip::Formats::Tar.open(path) do |reader|
+          entry = reader.entries.find { |e| e.name == entry_name }
+          raise Errno::ENOENT, "Entry not found: #{entry_name}" unless entry
+
+          data = entry.data
+        end
+        data
+      end
+    end
+  end
+end
+
+Omnizip::ArchiveHandler.register(:tar, Omnizip::ArchiveHandlers::TarHandler.new)