omnizip 0.4.9-arm-linux → 0.4.11-arm-linux

data/scripts/generate_rar_oracle_fixtures.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+# Regenerates the RAR oracle fixtures under spec/fixtures/rar/oracle/.
+#
+# The specs that used to shell out to `unrar` now assert against these
+# committed files, so CI never needs the rar/unrar oracle. When the
+# writers legitimately change their output, run:
+#
+#   bundle exec ruby scripts/generate_rar_oracle_fixtures.rb
+#
+# and commit the refreshed fixtures. The script FAILS unless the local
+# `unrar` oracle validates every generated archive, and unless each
+# writer is byte-deterministic across two runs (the specs compare fresh
+# writer output against these fixtures byte-for-byte).
+
+require "digest"
+require "fileutils"
+require "tmpdir"
+
+ROOT = File.expand_path("..", __dir__)
+DEST = File.join(ROOT, "spec/fixtures/rar/oracle")
+UNRAR = "unrar"
+# RAR5 embeds mtime as epoch seconds; pin it so fixtures are reproducible
+FIXED_TIME = Time.at(1_700_000_000)
+
+def sh!(*cmd)
+  system(*cmd) or abort("FAILED: #{cmd.join(' ')}")
+end
+
+def oracle_t(path)
+  sh!(UNRAR, "t", "-idq", path)
+end
+
+def oracle_listing(path)
+  out = `#{UNRAR} l #{path} 2>&1`
+  abort("unrar l failed for #{path}:\n#{out}") if out.include?("ERROR") || $?.success? == false
+  out
+end
+
+def build_rar5_single(dir)
+  input = File.join(dir, "in.txt")
+  File.binwrite(input, "Test content for unrar")
+  archive = File.join(dir, "rar5_single.rar")
+  writer = Omnizip::Formats::Rar::Rar5::Writer.new(archive)
+  writer.add_file(input, "test.txt")
+  writer.write
+  archive
+end
+
+def build_rar4_store_tree(dir)
+  big = File.join(dir, "big.txt")
+  File.binwrite(big, "omnizip RAR4 interop fixture. " * 800)
+  tree = File.join(dir, "tree")
+  FileUtils.mkdir_p(File.join(tree, "sub"))
+  File.binwrite(File.join(tree, "README.md"), "# tree\n")
+  File.binwrite(File.join(tree, "sub", "main.rb"), "puts 'hi'\n")
+  File.binwrite(File.join(tree, "empty.bin"), "")
+  archive = File.join(dir, "rar4_store_tree.rar")
+  writer = Omnizip::Formats::Rar::Writer.new(archive, compression: :store)
+  writer.add_file(big)
+  writer.add_directory(tree)
+  writer.write
+  archive
+end
+
+def build_rar5_multivolume(dir)
+  %w[compat0.txt compat1.txt].each_with_index do |name, i|
+    File.binwrite(File.join(dir, name), "Compatible content #{i}\n" * 3000)
+  end
+  archive = File.join(dir, "rar5_mv.rar")
+  writer = Omnizip::Formats::Rar::Rar5::Writer.new(
+    archive, multi_volume: true, volume_size: 65_536, compression: :store
+  )
+  writer.add_file(File.join(dir, "compat0.txt"))
+  writer.add_file(File.join(dir, "compat1.txt"))
+  volumes = writer.write
+  raise "expected split volumes, got #{volumes.size}" unless volumes.size > 1
+
+  volumes
+end
+
+def build_rar5_large(dir)
+  archive = File.join(dir, "rar5_large.rar")
+  writer = Omnizip::Formats::Rar5::Writer.new
+  io = StringIO.new
+  # RAR5 stores mtime as epoch seconds; the fixed constant keeps the bytes
+  # reproducible across machines and timezones.
+  writer.write_archive(io, [{ name: "large.txt", data: "X" * 10_000, time: FIXED_TIME }])
+  File.binwrite(archive, io.string)
+  archive
+end
+
+def build_rar5_store(dir)
+  input = File.join(dir, "test.txt")
+  File.write(input, "Test content for unrar")
+  archive = File.join(dir, "rar5_store_omnizip.rar")
+  writer = Omnizip::Formats::Rar::Rar5::Writer.new(archive, compression: :store)
+  writer.add_file(input, "test.txt")
+  writer.write
+  archive
+end
+
+def build_rar5_lzss_fallback(dir)
+  input = File.join(dir, "test.txt")
+  File.write(input, "Test content for unrar")
+  archive = File.join(dir, "rar5_lzss_fallback.rar")
+  writer = Omnizip::Formats::Rar::Rar5::Writer.new(archive,
+                                                   compression: :lzss, level: 3)
+  writer.add_file(input, "test.txt")
+  writer.write
+  archive
+end
+
+def build_rar5_multi_files(dir)
+  %w[file1.txt file2.txt].each_with_index do |name, i|
+    File.write(File.join(dir, name), "Content #{i + 1}\n" * 10)
+  end
+  archive = File.join(dir, "rar5_multi_files.rar")
+  writer = Omnizip::Formats::Rar::Rar5::Writer.new(archive,
+                                                   compression: :lzma, level: 3)
+  writer.add_file(File.join(dir, "file1.txt"), "file1.txt")
+  writer.add_file(File.join(dir, "file2.txt"), "file2.txt")
+  writer.write
+  archive
+end
+
+builders = {
+  "rar5_single" => method(:build_rar5_single),
+  "rar4_store_tree" => method(:build_rar4_store_tree),
+  "rar5_multivolume" => method(:build_rar5_multivolume),
+  "rar5_large" => method(:build_rar5_large),
+  "rar5_store_omnizip" => method(:build_rar5_store),
+  "rar5_lzss_fallback" => method(:build_rar5_lzss_fallback),
+  "rar5_multi_files" => method(:build_rar5_multi_files),
+}
+
+abort("unrar oracle not available — these fixtures can only be regenerated where unrar exists") unless system("which #{UNRAR} > /dev/null 2>&1")
+require "omnizip"
+
+FileUtils.mkdir_p(DEST)
+manifest = ["# RAR oracle fixtures — regenerated by scripts/generate_rar_oracle_fixtures.rb",
+            "# (unrar validated each archive at generation time; specs assert against these bytes)",
+            "generated: #{Time.now.utc.iso8601}",
+            "unrar_version: (derived from the first frozen listing's banner)",
+            "fixtures:"]
+
+builders.each do |name, builder|
+  puts "== #{name}"
+  Dir.mktmpdir("rar_oracle") do |dir|
+    built1 = builder.call(dir)
+    h1 = Array(built1).map { |p| Digest::SHA256.file(p).hexdigest }
+    h2 = Dir.mktmpdir("rar_oracle2") do |dir2|
+      Array(builder.call(dir2)).map { |p| Digest::SHA256.file(p).hexdigest }
+    end
+    abort("#{name}: writer not byte-deterministic across runs") unless h1 == h2
+
+    first = Array(built1).first
+    oracle_t(first)
+    listing = oracle_listing(first)
+    digest_pairs = Array(built1).zip(h1).map do |path, h|
+      base = name == "rar5_multivolume" ? File.basename(path) : "#{name}.rar"
+      dest = File.join(DEST, base)
+      FileUtils.cp(path, dest)
+      manifest << "  - file: #{base}"
+      manifest << "    sha256: #{h}"
+      base
+    end
+    listing_name = "#{name}.unrar-l.txt"
+    File.write(File.join(DEST, listing_name), listing)
+    manifest << "  - file: #{listing_name}"
+    manifest << "    oracle_listing_of: #{digest_pairs.first}"
+    puts "   frozen: #{digest_pairs.join(', ')}"
+  end
+end
+
+File.write(File.join(DEST, "MANIFEST.yml"), "#{manifest.join("\n")}\n")
+puts "done → #{DEST}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omnizip
 version: !ruby/object:Gem::Version
-  version: 0.4.9
+  version: 0.4.11
 platform: arm-linux
 authors:
 - Ribose Inc.
@@ -57,6 +57,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.4
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
 - !ruby/object:Gem::Dependency
   name: lutaml-model
   requirement: !ruby/object:Gem::Requirement
@@ -111,6 +125,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
+- ".rubocop-oss.yml"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - CHANGELOG.md
@@ -120,21 +135,6 @@ files:
 - LICENSE
 - README.adoc
 - Rakefile
-- TODO.refactor/00-overview.md
-- TODO.refactor/01-registry-base-class.md
-- TODO.refactor/02-error-hierarchy.md
-- TODO.refactor/03-autoload-entry-point.md
-- TODO.refactor/04-filter-base-consolidation.md
-- TODO.refactor/05-send-private-methods.md
-- TODO.refactor/06-instance-variable-access.md
-- TODO.refactor/07-respond-to-replacement.md
-- TODO.refactor/08-spec-doubles.md
-- TODO.refactor/09-cli-shared-module.md
-- TODO.refactor/10-format-detector-ocp.md
-- TODO.refactor/11-convenience-decoupling.md
-- TODO.refactor/12-thread-safety.md
-- TODO.refactor/13-lutaml-model-migration.md
-- TODO.refactor/14-add-missing-specs.md
 - benchmark/README.md
 - benchmark/benchmark_suite.rb
 - benchmark/compression_bench.rb
@@ -147,71 +147,13 @@ files:
 - benchmark/test_data.rb
 - config/formats/rar3_spec.yml
 - config/formats/rar5_spec.yml
-- docs/.github/workflows/docs.yml
-- docs/.gitignore
 - docs/.lychee.toml
-- docs/Gemfile
 - docs/RAR_WRITE_SUPPORT.md
-- docs/README.md
-- docs/_config.yml
 - docs/assets/logo.svg
 - docs/assets/omnizip-logo.pdf
-- docs/comparison/feature-matrix.adoc
-- docs/comparison/index.adoc
-- docs/comparison/vs-7zip.adoc
-- docs/comparison/vs-peazip.adoc
-- docs/comparison/vs-rubyzip.adoc
-- docs/comparison/vs-winrar.adoc
 - docs/compatibility.adoc
-- docs/concepts/index.adoc
-- docs/developer/architecture.adoc
-- docs/developer/contributing.adoc
-- docs/developer/index.adoc
-- docs/developer/testing.adoc
-- docs/getting-started/basic-usage.adoc
-- docs/getting-started/index.adoc
-- docs/getting-started/installation.adoc
-- docs/getting-started/quick-start.adoc
-- docs/getting-started/your-first-archive.adoc
-- docs/guides/advanced-features/encryption.adoc
-- docs/guides/advanced-features/index.adoc
-- docs/guides/advanced-features/parallel-processing.adoc
-- docs/guides/advanced-features/progress-tracking.adoc
-- docs/guides/advanced-features/streaming.adoc
-- docs/guides/archive-formats/gzip-format.adoc
-- docs/guides/archive-formats/index.adoc
-- docs/guides/archive-formats/ole-format.adoc
-- docs/guides/archive-formats/rar-format.adoc
-- docs/guides/archive-formats/rar5.adoc
-- docs/guides/archive-formats/rpm-format.adoc
-- docs/guides/archive-formats/seven-zip-format.adoc
-- docs/guides/archive-formats/tar-format.adoc
-- docs/guides/archive-formats/xz-format.adoc
-- docs/guides/archive-formats/zip-format.adoc
-- docs/guides/compression-algorithms/bzip2.adoc
-- docs/guides/compression-algorithms/deflate.adoc
-- docs/guides/compression-algorithms/index.adoc
-- docs/guides/compression-algorithms/lzma.adoc
-- docs/guides/compression-algorithms/lzma2.adoc
-- docs/guides/compression-algorithms/ppmd.adoc
-- docs/guides/compression-algorithms/zstandard.adoc
-- docs/guides/creating-archives.adoc
-- docs/guides/extracting-archives.adoc
-- docs/guides/format-conversion.adoc
-- docs/guides/index.adoc
-- docs/guides/migration-rubyzip.adoc
-- docs/guides/parity-archives.adoc
-- docs/guides/performance-tuning.adoc
-- docs/index.adoc
 - docs/lychee.toml
-- docs/reference/api/overview.adoc
-- docs/reference/cli/compress-command.adoc
-- docs/reference/cli/overview.adoc
-- docs/reference/index.adoc
-- docs/resources/faq.adoc
-- docs/resources/quick-reference.adoc
 - docs/rust-backend.md
-- docs/troubleshooting/index.adoc
 - docs/xar_format.md
 - examples/api_comparison.rb
 - examples/deflate64_example.rb
@@ -601,6 +543,8 @@ files:
 - lib/omnizip/implementations/base/state_machine_base.rb
 - lib/omnizip/implementations/rust.rb
 - lib/omnizip/implementations/rust/archive.rb
+- lib/omnizip/implementations/rust/ffi_library.rb
+- lib/omnizip/implementations/rust/fiddle_library.rb
 - lib/omnizip/implementations/rust/library.rb
 - lib/omnizip/implementations/seven_zip.rb
 - lib/omnizip/implementations/seven_zip/lzma.rb
@@ -722,6 +666,7 @@ files:
 - lib/omnizip/zip/file.rb
 - lib/omnizip/zip/input_stream.rb
 - lib/omnizip/zip/output_stream.rb
+- lib/tasks/docs.rake
 - lib/tasks/msi_test_files.rake
 - lib/tasks/platform_gems.rake
 - lib/tasks/rust_backend.rake
@@ -738,6 +683,8 @@ files:
 - readme-docs/par2-archives.adoc
 - readme-docs/performance-profiler.adoc
 - readme-docs/preprocessing-filters.adoc
+- readme-docs/rar-archives.adoc
+- scripts/generate_rar_oracle_fixtures.rb
 - vendor/libomnizip_ffi.so
 - xz-file-format-1.2.1.txt
 homepage: https://github.com/omnizip/omnizip

data/TODO.refactor/00-overview.md

@@ -1,67 +0,0 @@
-# 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 | **DONE** — 11 type checks converted; 45 feature-detection sites annotated `# allowed:` and enforced by a spec; 1 deferred type check in `algorithms/lzma.rb` pending `LzmaOptions` unification |
-| 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 | **DONE** — six models migrated; follow-ups 2+3 landed in 0.3.28; 1 and 4 decided (deferred rename / migration declined with reasons) |
-| 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?` | 60 at track 07 start (111 originally) | 49 — 46 annotated `# allowed:` (45 feature detection + 1 deferred type check) plus 3 doc comments |
-| 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

@@ -1,81 +0,0 @@
-# 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

@@ -1,57 +0,0 @@
-# 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

@@ -1,69 +0,0 @@
-# 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

@@ -1,49 +0,0 @@
-# 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`