omnizip 0.3.8 → 0.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb67186c4d0a7c3d4255db6fdfbc47895719621482f38ad7da46dcbdc5e9c901
-  data.tar.gz: 7610eb0253e8ddfc3c98283d850b5939340295f3a755d8efe77677c4794aa756
+  metadata.gz: d688703887c5ac25ffa43a48582dbb0580c74a94eff91d663d8e42c86943c4bb
+  data.tar.gz: ebe8ffdfddb46f63a508b4bc95e3d17ad85eef0e64ffe8e512d5c45f094cfedd
 SHA512:
-  metadata.gz: fcd49f7d89648284ed080479ca5cf24f9d28d0c11b01935d62c45575d9342341c4f6a86b6c28d11c9ff2c86d3bae70b166b8cad73cb5c64b8ea10c690778e299
-  data.tar.gz: a1218222877e813dcb45ceaceb89e9aeb84726ce38fa65a5db37a727862b5e53ba70462a1ac8723a1bc22271793f5692b89dc6168dc6eee6080e47b8a1a4d6b7
+  metadata.gz: 067dbae2e0301457c15fdeed52dacbb3d85376aa3282d6fa09e519b3853252db4d2cfffe53d95d71129aaecaef6f0f566d89088cd0fb242300f7f294ab9a3d18
+  data.tar.gz: 2d5777ce1a3bd115a5084fa4f3b2bae7b566087043978506c105cdbb905d8575912304eb6814b7d8d3ace483b1cd39833a76e03182e4d22930f09b3d6cbae63c

data/.rubocop_todo.yml

@@ -1,25 +1,23 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-02-23 11:56:10 UTC using RuboCop version 1.81.6.
+# on 2026-03-19 08:28:00 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
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 69
+# Offense count: 1
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'omnizip.gemspec'
+
+# Offense count: 5
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
-  Enabled: false
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_element, with_fixed_indentation
-Layout/ArrayAlignment:
   Exclude:
-    - 'lib/omnizip/implementations/seven_zip/lzma/decoder.rb'
+    - 'spec/omnizip/formats/seven_zip/embedded_search_spec.rb'
 
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
@@ -30,31 +28,19 @@ Layout/BlockAlignment:
     - 'lib/omnizip/algorithms/lzma/lzip_decoder.rb'
     - 'lib/omnizip/formats/xz_impl/block_decoder.rb'
 
-# Offense count: 10
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EmptyLineBetweenMethodDefs, EmptyLineBetweenClassDefs, EmptyLineBetweenModuleDefs, DefLikeMacros, AllowAdjacentOneLineDefs, NumberOfEmptyLines.
-Layout/EmptyLineBetweenDefs:
-  Exclude:
-    - 'lib/omnizip.rb'
-    - 'lib/omnizip/formats/rar.rb'
-
-# Offense count: 17
+# Offense count: 1485
 # This cop supports safe autocorrection (--autocorrect).
-Layout/EmptyLines:
-  Enabled: false
-
-# Offense count: 1831
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 69
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
-  Enabled: false
+  Exclude:
+    - 'spec/omnizip/formats/seven_zip/embedded_search_spec.rb'
 
 # Offense count: 13
 # Configuration parameters: AllowedMethods.
@@ -71,15 +57,16 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/omnizip/seven_zip_tool_compatibility_spec.rb'
     - 'spec/omnizip/xz_tool_compatibility_spec.rb'
 
-# Offense count: 34
+# Offense count: 36
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
 
-# Offense count: 8
+# Offense count: 9
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/omnizip/algorithms/lzma/xz_range_encoder_exact.rb'
+    - 'lib/omnizip/formats/msi/reader.rb'
     - 'lib/omnizip/formats/xz.rb'
     - 'lib/omnizip/implementations/xz_utils/lzma2/encoder.rb'
     - 'lib/omnizip/models/filter_config.rb'
@@ -127,13 +114,6 @@ Lint/StructNewOverride:
     - 'lib/omnizip/parallel/job_queue.rb'
     - 'lib/omnizip/parity/par2_creator.rb'
 
-# Offense count: 1
-# Configuration parameters: AllowedPatterns.
-# AllowedPatterns: (?-mix:(exactly|at_least|at_most)\(\d+\)\.times)
-Lint/UnreachableLoop:
-  Exclude:
-    - 'lib/omnizip/algorithms/lzma/range_decoder.rb'
-
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
@@ -148,38 +128,38 @@ Lint/UselessConstantScoping:
   Exclude:
     - 'lib/omnizip/algorithms/lzma/optimal_encoder.rb'
 
-# Offense count: 552
+# Offense count: 553
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 18
+# Offense count: 20
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 206
+  Max: 81
 
 # Offense count: 5
 # Configuration parameters: CountBlocks, CountModifierForms.
 Metrics/BlockNesting:
   Max: 6
 
-# Offense count: 266
+# Offense count: 263
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 948
+# Offense count: 961
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 434
+  Max: 238
 
 # Offense count: 33
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 20
 
-# Offense count: 187
+# Offense count: 182
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -193,22 +173,19 @@ Naming/MethodParameterName:
 # Offense count: 38
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
 # AllowedMethods: call
-# WaywardPredicates: nonzero?
+# WaywardPredicates: infinite?, nonzero?
 Naming/PredicateMethod:
   Enabled: false
 
-# Offense count: 42
+# Offense count: 37
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
 # AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
 Naming/VariableNumber:
   Exclude:
     - 'lib/omnizip/algorithms/lzma/bit_model.rb'
-    - 'lib/omnizip/algorithms/lzma/distance_coder.rb'
-    - 'lib/omnizip/algorithms/lzma/literal_decoder.rb'
     - 'lib/omnizip/algorithms/lzma/range_encoder.rb'
     - 'lib/omnizip/algorithms/lzma/xz_buffered_range_encoder.rb'
-    - 'lib/omnizip/algorithms/lzma/xz_utils_decoder.rb'
     - 'lib/omnizip/formats/rar/rar5/compression/lzss.rb'
     - 'lib/omnizip/formats/xz_impl/block_decoder.rb'
     - 'lib/omnizip/implementations/seven_zip/lzma/range_encoder.rb'
@@ -218,13 +195,14 @@ Naming/VariableNumber:
     - 'spec/omnizip/parity/reed_solomon_encoder_spec.rb'
     - 'spec/omnizip/parity/reed_solomon_matrix_spec.rb'
 
-# Offense count: 8
+# Offense count: 9
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
   Exclude:
     - 'lib/omnizip/commands/archive_create_command.rb'
     - 'lib/omnizip/formats/iso/directory_builder.rb'
     - 'lib/omnizip/formats/iso/writer.rb'
+    - 'lib/omnizip/formats/msi/constants.rb'
     - 'lib/omnizip/formats/seven_zip/header_writer.rb'
     - 'lib/omnizip/parity/models/file_description_packet.rb'
     - 'lib/omnizip/parity/par2_repairer.rb'
@@ -235,12 +213,14 @@ Performance/MapMethodChain:
   Exclude:
     - 'lib/omnizip/commands/archive_create_command.rb'
 
-# Offense count: 7
+# Offense count: 11
 Security/Open:
   Exclude:
     - 'lib/omnizip/formats/cpio.rb'
     - 'lib/omnizip/formats/iso.rb'
+    - 'lib/omnizip/formats/msi.rb'
     - 'lib/omnizip/zip/file.rb'
+    - 'lib/tasks/msi_test_files.rake'
 
 # Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
@@ -260,6 +240,20 @@ Style/EmptyElse:
     - 'lib/omnizip/algorithms/ppmd7/encoder.rb'
     - 'lib/omnizip/formats/iso/volume_descriptor.rb'
 
+# Offense count: 11
+Style/FileOpen:
+  Exclude:
+    - 'lib/omnizip/chunked/writer.rb'
+    - 'lib/omnizip/formats/iso/reader.rb'
+    - 'lib/omnizip/formats/rar/rar5/multi_volume/volume_writer.rb'
+    - 'lib/omnizip/formats/rpm.rb'
+    - 'lib/omnizip/formats/seven_zip/split_archive_writer.rb'
+    - 'lib/omnizip/formats/tar/writer.rb'
+    - 'lib/omnizip/formats/xar/reader.rb'
+    - 'lib/omnizip/zip/input_stream.rb'
+    - 'lib/omnizip/zip/output_stream.rb'
+    - 'spec/omnizip/formats/rpm_spec.rb'
+
 # Offense count: 161
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: MaxUnannotatedPlaceholdersAllowed, Mode, AllowedMethods, AllowedPatterns.
@@ -273,6 +267,13 @@ Style/MixinUsage:
     - 'spec/scripts/debug_7z_structure.rb'
     - 'spec/scripts/debug_writer_output.rb'
 
+# Offense count: 3
+# Configuration parameters: AllowedClasses.
+Style/OneClassPerFile:
+  Exclude:
+    - 'lib/omnizip.rb'
+    - 'lib/omnizip/algorithms/lzma2.rb'
+
 # Offense count: 3
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?

data/Gemfile

@@ -5,6 +5,8 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in omnizip.gemspec
 gemspec
 
+# For spec testing
+gem "csv"
 gem "rake"
 gem "rspec"
 gem "rubocop"

data/Rakefile

@@ -9,4 +9,7 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+# Load custom rake tasks
+Dir["lib/tasks/*.rake"].each { |task| load task }
+
 task default: %i[spec rubocop]

data/TODO.refactor/00-overview.md

@@ -0,0 +1,67 @@
+# 00 — Refactor Plan Overview
+
+Date: 2026-07-20 (updated 2026-07-21)
+Scope: `lib/` and `spec/` of the omnizip gem.
+
+## Goals
+
+Apply OCP, DRY, MECE, model-driven design, open/closed principle, and high
+performance to the omnizip codebase. Eliminate the anti-patterns declared
+as absolute rules:
+
+- `require_relative` (and internal `require`) inside `lib/`
+- `.send` against private methods (breaks encapsulation)
+- `instance_variable_set` / `instance_variable_get` on other objects
+- `respond_to?` as a substitute for proper typing
+- `double()` in specs (use real instances or `Struct`)
+- Hand-rolled `to_h` / `from_h` / `to_json` on model classes (use `lutaml-model`)
+
+## Track status
+
+| # | File | Priority | Status |
+|---|---|---|---|
+| 01 | `01-registry-base-class.md` | high | **DONE** |
+| 02 | `02-error-hierarchy.md` | high | **DONE** |
+| 03 | `03-autoload-entry-point.md` | high | **DONE** |
+| 04 | `04-filter-base-consolidation.md` | medium | **DONE** |
+| 05 | `05-send-private-methods.md` | high | **DONE** |
+| 06 | `06-instance-variable-access.md` | high | **DONE** |
+| 07 | `07-respond-to-replacement.md` | medium | **PARTIAL** — IO::Source/Sink adapter built; type-check sites converted; ~76 IO capability checks remain in xz_impl/* and ole/* (legitimate duck-typing for ungetbyte / set_encoding etc.) |
+| 08 | `08-spec-doubles.md` | low | **DONE** |
+| 09 | `09-cli-shared-module.md` | low | **DONE** |
+| 10 | `10-format-detector-ocp.md` | medium | **DONE** |
+| 11 | `11-convenience-decoupling.md` | medium | **DONE** (ArchiveHandler dispatcher + ZipHandler + TarHandler) |
+| 12 | `12-thread-safety.md` | covered by 01 | n/a |
+| 13 | `13-lutaml-model-migration.md` | medium | **PARTIAL** — CompressionOptions and AlgorithmMetadata migrated; ConversionOptions pending lutaml symbol-type support |
+| 14 | `14-add-missing-specs.md` | high | **DONE** |
+
+## Anti-pattern counts (lib/)
+
+| Pattern | Before | After |
+|---|---|---|
+| `require_relative` / `require "omnizip/..."` | ~290 | **0** |
+| `.send` on private methods | 17 | **0** |
+| `instance_variable_set`/`get` | 54 | **0** |
+| `double()` in specs | 1 | **0** |
+| `respond_to?` | 111 | 76 (mostly IO capability detection) |
+| Hand-rolled model `to_h` | 26 | 24 (2 migrated to lutaml-model) |
+
+## Architecture summary
+
+- **`Omnizip::Registry`** — thread-safe base class with lazy-load triggers.
+- **`Omnizip::IO::Source` / `Sink`** — polymorphic adapters for
+  String/Path/IO/StringIO/Tempfile.
+- **`Omnizip::ArchiveHandler`** — dispatcher decoupling Convenience from
+  ZIP. New formats plug in by registering a handler.
+- **`Omnizip::Platform`** — predicates for symlink/hardlink/NTFS support.
+- **Error hierarchy** consolidated with backward-compat aliases.
+- **`Filter` / `FilterBase`** unified.
+
+## Test coverage
+
+3643 examples, 0 failures. New specs:
+
+- `spec/omnizip/registry_spec.rb`
+- `spec/omnizip/error_spec.rb`
+- `spec/omnizip/io/source_spec.rb`
+- `spec/omnizip/convenience_tar_spec.rb`

data/TODO.refactor/01-registry-base-class.md

@@ -0,0 +1,81 @@
+# 01 — Registry base class
+
+Priority: **high**.
+Status: TODO.
+
+## Problem
+
+Five registry classes duplicate an identical pattern:
+
+- `Omnizip::AlgorithmRegistry` (`lib/omnizip/algorithm_registry.rb`)
+- `Omnizip::FormatRegistry` (`lib/omnizip/format_registry.rb`)
+- `Omnizip::FilterRegistry` (`lib/omnizip/filter_registry.rb`)
+- `Omnizip::ChecksumRegistry` (`lib/omnizip/checksum_registry.rb`)
+- `Omnizip::OptimizationRegistry` (`lib/omnizip/optimization_registry.rb`)
+- `Omnizip::Password::EncryptionRegistry` (`lib/omnizip/password/encryption_registry.rb`)
+- `Omnizip::Converter::ConversionRegistry` (`lib/omnizip/converter/conversion_registry.rb`)
+
+Each implements a slightly different version of `register / get /
+registered? / available / reset` with different naming, error classes, and
+key-normalization rules.
+
+Inconsistencies:
+
+| Registry | Storage | Reset | Not-found error |
+|---|---|---|---|
+| AlgorithmRegistry | `@algorithms ||= {}` | `reset!` | `UnknownAlgorithmError` |
+| FormatRegistry | `@registry ||= {}` | (none) | returns nil |
+| FilterRegistry | `@filters = {}` | `reset!` | `UnknownFilterError` |
+| ChecksumRegistry | `@checksums = {}` | `clear` | `UnknownAlgorithmError` |
+| OptimizationRegistry | `@strategies ||= {}` | `clear!` | `OptimizationNotFound` |
+| EncryptionRegistry | `@strategies = {}` | `reset` | `ArgumentError` |
+| ConversionRegistry | array of classes | `reset` | returns nil |
+
+None are thread-safe.
+
+## Plan
+
+1. Create `lib/omnizip/registry.rb` defining `Omnizip::Registry` — a
+   thread-safe generic registry with:
+   - `register(name, value, **opts)` (overrides per subclass)
+   - `get(name)` → raises `not_found_error` if missing
+   - `registered?(name)` → bool
+   - `available` / `all` → keys
+   - `reset!` → clears store (canonical name)
+   - `Mutex`-synchronized mutations
+   - Configurable `not_found_error` class and `normalize_key` hook.
+
+2. Migrate each registry to inherit from `Omnizip::Registry`. Preserve the
+   existing public class names and method names so call sites still work.
+   For backward compatibility, alias `clear`/`reset` to `reset!`,
+   `supported_formats`/`strategies` to `available` where applicable.
+
+3. FormatRegistry keeps `normalize_extension` as its `normalize_key` hook.
+
+4. FilterRegistry keeps its `formats:` registry metadata and
+   `get_for_format` / `supports_format?` / `filters_for_format` extensions
+   on top of the base.
+
+5. ConversionRegistry is array-based and is the only outlier; leave as-is
+   or convert to a key based on `[source, target]` tuple. Pragmatically:
+   leave as-is, document why.
+
+## Acceptance
+
+- All existing registry specs pass unchanged.
+- `bundle exec rspec` failure count is ≤ baseline (2).
+- No new rubocop offenses.
+- `lib/omnizip/registry_spec.rb` covers register/get/registered?/reset! and
+  thread-safety smoke test.
+
+## Files to touch
+
+- create `lib/omnizip/registry.rb`
+- create `spec/omnizip/registry_spec.rb`
+- modify `lib/omnizip/algorithm_registry.rb`
+- modify `lib/omnizip/format_registry.rb`
+- modify `lib/omnizip/filter_registry.rb`
+- modify `lib/omnizip/checksum_registry.rb`
+- modify `lib/omnizip/optimization_registry.rb`
+- modify `lib/omnizip/password/encryption_registry.rb`
+- modify `lib/omnizip.rb` to autoload `:Registry`

data/TODO.refactor/02-error-hierarchy.md

@@ -0,0 +1,57 @@
+# 02 — Error hierarchy consolidation
+
+Priority: **high**.
+Status: TODO.
+
+## Problems
+
+1. `AlgorithmNotFoundError` and `UnknownAlgorithmError` both exist in
+   `lib/omnizip/error.rb` and are used interchangeably. The two registries
+   that raise on miss (`AlgorithmRegistry`, `ChecksumRegistry`) both raise
+   `UnknownAlgorithmError`.
+2. `OptimizationNotFound` lacks the `Error` suffix convention.
+3. `Omnizip::IOError` shadows Ruby's built-in `IOError` — confusing for
+   users who `rescue IOError`.
+4. `UnknownFilterError` is defined at the bottom of
+   `lib/omnizip/filter_registry.rb` instead of `lib/omnizip/error.rb`.
+5. `EncryptionRegistry` raises vanilla `ArgumentError` instead of a
+   domain-specific error.
+6. `ConversionRegistry` returns nil instead of raising.
+
+## Plan
+
+1. In `lib/omnizip/error.rb`:
+   - Keep `AlgorithmNotFoundError` as canonical; make
+     `UnknownAlgorithmError` an alias (subclass) for backward compatibility.
+     Document the alias.
+   - Rename `OptimizationNotFound` → `OptimizationNotFoundError`. Keep the
+     old name as an alias for backward compatibility.
+   - Rename `IOError` → `IOOperationError`. Keep `IOError` as an alias for
+     backward compatibility (or deprecate it).
+   - Add `UnknownFilterError` to `error.rb` (and remove from
+     `filter_registry.rb`).
+   - Add `UnknownEncryptionStrategyError < Error`.
+   - Add `ConversionNotSupportedError < Error`.
+
+2. Update all internal `raise` sites to use the canonical names.
+
+3. Update `FormatRegistry`, `ConversionRegistry` to raise their new errors
+   instead of returning nil where the caller cannot reasonably handle nil.
+
+4. Update `lib/omnizip.rb` autoload entries to include the new error names.
+
+## Acceptance
+
+- All existing specs pass.
+- No new rubocop offenses.
+- `lib/omnizip/error_spec.rb` confirms hierarchy and aliases.
+
+## Files
+
+- modify `lib/omnizip/error.rb`
+- modify `lib/omnizip/filter_registry.rb` (remove inline error)
+- modify `lib/omnizip/optimization_registry.rb` (raise renamed error)
+- modify `lib/omnizip/password/encryption_registry.rb` (raise new error)
+- modify `lib/omnizip/converter/conversion_registry.rb` (raise on miss)
+- modify `lib/omnizip.rb` autoload list
+- create `spec/omnizip/error_spec.rb`

data/TODO.refactor/03-autoload-entry-point.md

@@ -0,0 +1,69 @@
+# 03 — Autoload entry point
+
+Priority: **high**.
+Status: TODO.
+
+## Problem
+
+`lib/omnizip.rb` lines 99–139 contain 31 `require_relative` calls for
+algorithms, filters, checksums, and formats. Per the global rule,
+`require_relative` is forbidden inside `lib/`. The justification given is
+"these classes self-register at load time" — but self-registration only
+needs to happen *before first lookup*, not at gem boot.
+
+Additional inconsistency: line 179 uses `require "omnizip/convenience"`
+while similar modules are autoloaded.
+
+## Plan
+
+1. Convert each `require_relative` line in `lib/omnizip.rb` to an autoload
+   declaration in the appropriate namespace:
+
+   ```ruby
+   module Omnizip
+     module Algorithms
+       autoload :LZMA, "omnizip/algorithms/lzma"
+       autoload :LZMA2, "omnizip/algorithms/lzma2"
+       # ...
+     end
+   end
+   ```
+
+2. For self-registering classes, keep the registration call at the bottom
+   of each implementation file (`AlgorithmRegistry.register(:lzma, LZMA)`).
+   Autoload will load the file on first reference, which triggers
+   registration. Tests that pre-populate the registry should reference the
+   constant first (e.g., `Omnizip::Algorithms::LZMA`).
+
+3. For files that are currently eager-required because *nothing else*
+   references them (only the registration matters), add an explicit
+   autoload entry in the right namespace *and* arrange for the constant to
+   be referenced on first registry miss. Concretely: change registries to
+   trigger autoload by referencing the constant rather than calling
+   `register` from the file body. See `08-registry-lazy-trigger.md` if a
+   fallback is needed.
+
+4. Replace the trailing `require "omnizip/convenience"` with an autoload
+   entry — `autoload :Convenience, "omnizip/convenience"` — and reference
+   it lazily where used (or eager-load at the very end of `lib/omnizip.rb`
+   via `require "omnizip/convenience"` ONLY if Convenience must extend
+   Omnizip at boot; document why).
+
+5. Run specs. If any spec fails because a class never autoloaded, fix by
+   adding a `require` at the top of the spec file (specs are NOT subject
+   to the no-`require_relative` rule for library code; they ARE subject to
+   it for sibling spec files but not for library files).
+
+## Acceptance
+
+- `grep -rn "require_relative" lib/` returns zero matches.
+- `grep -rn '^require "omnizip/' lib/` is limited to the convenience
+  fallback (documented) and any in-file registration triggers.
+- All specs pass.
+
+## Files
+
+- modify `lib/omnizip.rb` (replace lines 99–139 and line 179)
+- ensure each `lib/omnizip/algorithms/*.rb`, `lib/omnizip/filters/*.rb`,
+  `lib/omnizip/checksums/*.rb`, `lib/omnizip/formats/*.rb` ends with its
+  own registration call (most already do).

data/TODO.refactor/04-filter-base-consolidation.md

@@ -0,0 +1,49 @@
+# 04 — Filter base consolidation
+
+Priority: **medium**.
+Status: TODO.
+
+## Problem
+
+Two parallel base classes exist:
+
+- `Omnizip::Filter` (`lib/omnizip/filter.rb`) — has `architecture` and
+  `name` attrs plus `id_for_format(format)`. Used by `BCJ` and `Delta`.
+- `Omnizip::Filters::FilterBase` (`lib/omnizip/filters/filter_base.rb`) —
+  minimal `encode`/`decode`/`.metadata` stub. Used by `BcjX86`, `BcjArm`,
+  `BcjArm64`, `BcjIa64`, `BcjPpc`, `BcjSparc`, `Bcj2`.
+
+They share identical `encode(data, position=0)` / `decode(data,
+position=0)` / `.metadata` stubs. `FilterBase` is a subset of `Filter`.
+
+## Plan
+
+1. Keep `Filter` as the canonical base, located at
+   `lib/omnizip/filters/base.rb`. Make `architecture` optional (defaults
+   to nil).
+2. Make `Omnizip::Filters::FilterBase` an alias / subclass of the unified
+   base for backward compatibility.
+3. Migrate subclasses of `FilterBase` to inherit from the unified base.
+4. Delete the body of `lib/omnizip/filters/filter_base.rb`, leaving it as
+   a backward-compat alias:
+   ```ruby
+   require "omnizip/filters/base"
+   module Omnizip::Filters
+   FilterBase = Filter  # backward-compat alias
+   end
+   ```
+   (or define `FilterBase < Filter` if a true subclass is preferred.)
+
+## Acceptance
+
+- All filter specs pass.
+- No public API breaks.
+- `lib/omnizip/filter.rb` removed or stubbed to alias.
+
+## Files
+
+- modify `lib/omnizip/filter.rb`
+- create or modify `lib/omnizip/filters/base.rb`
+- modify `lib/omnizip/filters/filter_base.rb` (alias)
+- modify each subclass to inherit from the new base
+- add autoload entry in `lib/omnizip/filters.rb`

data/TODO.refactor/05-send-private-methods.md

@@ -0,0 +1,64 @@
+# 05 — Eliminate `.send` against private methods
+
+Priority: **high**.
+Status: TODO.
+
+## Rule
+
+> NEVER use `send` to call private methods. Private methods are private
+> for a reason. If you need to call it from outside, the API boundary is
+> wrong — redesign, don't bypass.
+
+## Inventory (17 occurrences)
+
+| File:Line | Call | Fix |
+|---|---|---|
+| `lib/omnizip/parity.rb:178` | `verifier.send(:parse_par2_file)` | Promote to public |
+| `lib/omnizip/parity.rb:180` | `verifier.send(:calculate_total_blocks)` | Promote to public |
+| `lib/omnizip/parity/par2_repairer.rb:174` | `@verifier.send(:find_file_path, ...)` | Promote to public |
+| `lib/omnizip/parallel/parallel_compressor.rb:306` | `writer.send(:create_entry, ...)` | Promote to public |
+| `lib/omnizip/parallel/parallel_compressor.rb:324` | `writer.send(:write_with_precompressed_data, ...)` | Promote |
+| `lib/omnizip/parallel/parallel_compressor.rb:136` | `opts.send(:"#{k}=", v)` | Replace with `CompressionOptions#apply(hash)` |
+| `lib/omnizip/parallel/parallel_extractor.rb:110` | `reader.send(:decompress_data, ...)` | Promote to public |
+| `lib/omnizip/parallel/parallel_extractor.rb:135` | `opts.send(:"#{k}=", v)` | Same as above |
+| `lib/omnizip/formats/format_spec_loader.rb:203` | `format.send(key)` | Replace with explicit dispatch |
+| `lib/omnizip/converter/seven_zip_to_zip_strategy.rb:62` | `reader.send(:extract_entry_data, ...)` | Promote to public |
+| `lib/omnizip/formats/seven_zip/parser.rb:573` | `entry.send(:"#{attr}=", ...)` | Add public writer or ctor arg |
+| `lib/omnizip/formats/rpm/header.rb:36` | `header.send(:parse!, io)` | Promote `parse!` to public |
+| `lib/omnizip/algorithms/zstandard/frame/header.rb:72,76,80` | `header.send(:parse_window_descriptor, ...)` etc. | Promote parse helpers to public, or inline |
+| `lib/omnizip/zip/file.rb:419` | `@reader.send(:decompress_data, ...)` | Promote to public |
+| `lib/omnizip/crypto/aes256/cipher.rb:90` | `cipher.send(mode)` | Replace with explicit `if encrypt? ... else ...` |
+
+## Plan
+
+For each call site, choose ONE of:
+
+1. **Promote the method to public.** If callers legitimately need it, the
+   `private` declaration was wrong. Add a doc comment and make it public.
+2. **Add a public facade.** Keep the private method, expose a public
+   method with a clearer name that wraps it.
+3. **Inline the call.** Sometimes the private method is one line and the
+   `.send` is just laziness — inline the body.
+
+`opts.send(:"#{k}=", v)` (parallel_compressor.rb:136 and
+parallel_extractor.rb:135) deserves a real fix: add
+`CompressionOptions#apply(attributes)` and `ParallelOptions#apply` methods
+that take a hash and set attributes via `public_send` only on whitelisted
+keys.
+
+`format.send(key)` (format_spec_loader.rb:203) is data-driven dispatch on
+a spec format — replace with a hash of known keys → lambdas, or with a
+case statement that calls public methods explicitly.
+
+`cipher.send(mode)` (crypto/aes256/cipher.rb:90) — replace with an
+explicit branch on whether to call `encrypt` or `decrypt`.
+
+## Acceptance
+
+- `grep -rn "\.send(" lib/` returns at most a handful of intentional
+  metaprogramming cases (e.g., `public_send` with documented reason).
+- All specs pass.
+
+## Files
+
+See table above. 11 files to modify.