omnizip 0.3.9 → 0.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb35ab3f87d9e1a1d4f96c65a86b9c5dcbd5df0f4da48443158dbe16d8e896e0
-  data.tar.gz: f9c8deab498097486bb07092f479b5097959cbc7f6b6ca171bc79996b08b6b91
+  metadata.gz: d688703887c5ac25ffa43a48582dbb0580c74a94eff91d663d8e42c86943c4bb
+  data.tar.gz: ebe8ffdfddb46f63a508b4bc95e3d17ad85eef0e64ffe8e512d5c45f094cfedd
 SHA512:
-  metadata.gz: b518a237a3f41aac1d2e30d88cbc0e872320141d7f705d2bc33db3a2fbe22c5f784b8219c88001c54706571d07a3aa858f068c249e1da20efeb7c2afaca2f234
-  data.tar.gz: a18702ca45df7e9b6176b397c33d0e852a3a8a3880f58be16567aa13be7472c52b4774595a7fe1b90f3ef3929bab29d70e18ea22e4184add6a21b2c38c501909
+  metadata.gz: 067dbae2e0301457c15fdeed52dacbb3d85376aa3282d6fa09e519b3853252db4d2cfffe53d95d71129aaecaef6f0f566d89088cd0fb242300f7f294ab9a3d18
+  data.tar.gz: 2d5777ce1a3bd115a5084fa4f3b2bae7b566087043978506c105cdbb905d8575912304eb6814b7d8d3ace483b1cd39833a76e03182e4d22930f09b3d6cbae63c

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.

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.