omnizip 0.3.1

data/benchmark/test_data.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Benchmark
+  # Generates test data files for benchmarking compression algorithms
+  class TestData
+    LOREM_IPSUM = <<~TEXT
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
+      enim ad minim veniam, quis nostrud exercitation ullamco laboris
+      nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
+      in reprehenderit in voluptate velit esse cillum dolore eu fugiat
+      nulla pariatur. Excepteur sint occaecat cupidatat non proident,
+      sunt in culpa qui officia deserunt mollit anim id est laborum.
+    TEXT
+
+    attr_reader :data_dir
+
+    def initialize(data_dir = "benchmark/data")
+      @data_dir = data_dir
+      FileUtils.mkdir_p(@data_dir)
+    end
+
+    def generate_text(size, filename: "text.txt")
+      path = File.join(data_dir, filename)
+      content = generate_lorem_text(size)
+      File.binwrite(path, content)
+      path
+    end
+
+    def generate_source_code(size, filename: "source.rb")
+      path = File.join(data_dir, filename)
+      content = generate_ruby_source(size)
+      File.binwrite(path, content)
+      path
+    end
+
+    def generate_repetitive(size, filename: "repetitive.bin")
+      path = File.join(data_dir, filename)
+      pattern = "ABCDEFGH" * 32
+      content = (pattern * ((size / pattern.bytesize) + 1))[0, size]
+      File.binwrite(path, content)
+      path
+    end
+
+    def generate_random(size, filename: "random.bin")
+      path = File.join(data_dir, filename)
+      content = Random.bytes(size)
+      File.binwrite(path, content)
+      path
+    end
+
+    def generate_multimedia(size, filename: "multimedia.bin")
+      path = File.join(data_dir, filename)
+      content = generate_gradient_data(size)
+      File.binwrite(path, content)
+      path
+    end
+
+    def cleanup
+      FileUtils.rm_rf(data_dir)
+      FileUtils.mkdir_p(data_dir)
+    end
+
+    private
+
+    def generate_lorem_text(size)
+      paragraphs = []
+      current_size = 0
+
+      while current_size < size
+        paragraphs << LOREM_IPSUM
+        current_size += LOREM_IPSUM.bytesize
+      end
+
+      paragraphs.join("\n\n")[0, size]
+    end
+
+    def generate_ruby_source(size)
+      code = <<~RUBY
+        # frozen_string_literal: true
+
+        module Example
+          class DataProcessor
+            attr_reader :data
+
+            def initialize(data)
+              @data = data
+            end
+
+            def process
+              data.map { |item| transform(item) }
+            end
+
+            def transform(item)
+              item.upcase.reverse
+            end
+
+            def filter(predicate)
+              data.select { |item| predicate.call(item) }
+            end
+
+            def aggregate
+              data.inject(0) { |sum, item| sum + item.length }
+            end
+          end
+        end
+      RUBY
+
+      lines = []
+      current_size = 0
+
+      counter = 0
+      while current_size < size
+        lines << code
+        counter += 1
+        lines << "\n# Generated code block #{counter}\n"
+        current_size = lines.join.bytesize
+      end
+
+      lines.join[0, size]
+    end
+
+    def generate_gradient_data(size)
+      data = []
+      step = 256.0 / [size, 256].min
+
+      size.times do |i|
+        value = ((i * step) % 256).to_i
+        data << value.chr
+      end
+
+      data.join
+    end
+  end
+end

data/config/formats/rar3_spec.yml

@@ -0,0 +1,91 @@
+# RAR v3 Format Specification
+# Based on RAR 3.x archive format
+
+format:
+  name: "RAR3"
+  version: "3.0"
+  extension: ".rar"
+
+  # RAR 3.x signature: "Rar!\x1A\x07\x00"
+  magic_bytes: [0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x00]
+
+  block_types:
+    marker: 0x72        # Archive marker block
+    archive: 0x73       # Archive header block
+    file: 0x74          # File header block
+    comment: 0x75       # Comment header block
+    old_auth: 0x76      # Old-style authentication block
+    old_subblock: 0x77  # Old-style subblock
+    recovery: 0x78      # Recovery record block
+    auth: 0x79          # Authentication block
+    subblock: 0x7A      # Subblock
+    terminator: 0x7B    # Archive end block
+
+  archive_flags:
+    volume: 0x0001           # Archive volume
+    comment: 0x0002          # Archive comment present
+    lock: 0x0004             # Archive locked
+    solid: 0x0008            # Solid archive
+    new_naming: 0x0010       # New volume naming scheme
+    auth_info: 0x0020        # Authenticity information present
+    recovery: 0x0040         # Recovery record present
+    encrypted: 0x0080        # Block headers encrypted
+    first_volume: 0x0100     # First volume
+
+  file_flags:
+    split_before: 0x0001     # File continued from previous volume
+    split_after: 0x0002      # File continued in next volume
+    encrypted: 0x0004        # File encrypted
+    comment: 0x0008          # File comment present
+    solid: 0x0010            # Information from previous files used
+    dictionary_mask: 0x00E0  # Dictionary size (bits 5-7)
+    large_file: 0x0100       # file64 operations
+    unicode: 0x0200          # Filename is Unicode
+    salt: 0x0400             # Salt present
+    version: 0x0800          # Version flag
+    ext_time: 0x1000         # Extended time field present
+    ext_flags: 0x2000        # Extended flags field
+
+  compression_methods:
+    store: 0x30              # No compression
+    fastest: 0x31            # Fastest compression
+    fast: 0x32               # Fast compression
+    normal: 0x33             # Normal compression
+    good: 0x34               # Good compression
+    best: 0x35               # Best compression
+
+  host_os:
+    msdos: 0                 # MS DOS
+    os2: 1                   # OS/2
+    win32: 2                 # Windows
+    unix: 3                  # Unix
+    macos: 4                 # Mac OS
+    beos: 5                  # BeOS
+
+  dictionary_sizes:
+    64k: 0                   # 64 KB
+    128k: 1                  # 128 KB
+    256k: 2                  # 256 KB
+    512k: 3                  # 512 KB
+    1024k: 4                 # 1024 KB (1 MB)
+    2048k: 5                 # 2048 KB (2 MB)
+    4096k: 6                 # 4096 KB (4 MB)
+    auto: 7                  # Auto-detect
+
+  encryption:
+    supported: true
+    algorithms:
+      - aes128
+      - aes256
+    key_derivation: pbkdf2
+    salt_size: 8
+
+  features:
+    recovery_records: true
+    solid_archives: true
+    multivolume: true
+    file_comments: true
+    archive_comments: true
+    unicode_filenames: true
+    large_files: true        # > 4 GB
+    extended_timestamps: true

data/config/formats/rar5_spec.yml

@@ -0,0 +1,102 @@
+# RAR v5 Format Specification
+# Based on RAR 5.x archive format
+
+format:
+  name: "RAR5"
+  version: "5.0"
+  extension: ".rar"
+
+  # RAR 5.x signature: "Rar!\x1A\x07\x01\x00"
+  magic_bytes: [0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x01, 0x00]
+
+  block_types:
+    main_header: 0x01        # Main archive header
+    file_header: 0x02        # File header
+    service_header: 0x03     # Service header
+    encryption_header: 0x04  # Archive encryption header
+    end_marker: 0x05         # End of archive marker
+
+  main_header_flags:
+    volume: 0x0001           # Archive is volume
+    volume_number: 0x0002    # Volume number field present
+    solid: 0x0004            # Solid archive
+    recovery: 0x0008         # Recovery record present
+    locked: 0x0010           # Archive locked
+
+  file_header_flags:
+    directory: 0x0001        # Entry is a directory
+    time_present: 0x0002     # Time field present
+    crc32_present: 0x0004    # CRC32 field present
+    unpacked_size_unknown: 0x0008  # Unpacked size is unknown
+
+  encryption_flags:
+    password_check: 0x0001   # Check password present
+    use_mac: 0x0002          # Use MAC
+
+  compression_methods:
+    store: 0               # No compression
+    fastest: 1             # Fastest compression
+    fast: 2                # Fast compression
+    normal: 3              # Normal compression
+    good: 4                # Good compression
+    best: 5                # Best compression (maximum)
+
+  # RAR 5 uses BLAKE2sp for checksums
+  checksum:
+    algorithm: blake2sp
+    size: 32  # bytes
+
+  host_os:
+    windows: 0             # Windows
+    unix: 1                # Unix/Linux
+
+  dictionary_sizes:
+    128k: 0                # 128 KB
+    256k: 1                # 256 KB
+    512k: 2                # 512 KB
+    1024k: 3               # 1024 KB (1 MB)
+    2048k: 4               # 2048 KB (2 MB)
+    4096k: 5               # 4096 KB (4 MB)
+    8192k: 6               # 8192 KB (8 MB)
+    16384k: 7              # 16384 KB (16 MB)
+    32768k: 8              # 32768 KB (32 MB)
+    65536k: 9              # 65536 KB (64 MB)
+    131072k: 10            # 131072 KB (128 MB)
+    262144k: 11            # 262144 KB (256 MB)
+    524288k: 12            # 524288 KB (512 MB)
+    1048576k: 13           # 1048576 KB (1024 MB / 1 GB)
+
+  encryption:
+    supported: true
+    algorithms:
+      - aes256
+    key_derivation: pbkdf2
+    kdf_iterations: 262144  # PBKDF2 iterations
+    salt_size: 16          # bytes
+
+  compression_features:
+    solid_archives: true
+    multivolume: true
+    recovery_records: true
+    unicode_filenames: true  # UTF-8 encoding
+    large_files: true        # No size limitations
+    extended_timestamps: true
+    64bit_sizes: true
+
+  # RAR 5 specific features
+  advanced_features:
+    blake2_checksums: true
+    improved_compression: true
+    better_unicode: true
+    optional_crc32: true
+    extended_time_format: true
+
+  # Extra record types
+  extra_records:
+    encryption: 0x01
+    hash: 0x02
+    time: 0x03
+    version: 0x04
+    redirection: 0x05
+    owner: 0x06
+    service: 0x07

data/docs/.github/workflows/docs.yml

@@ -0,0 +1,142 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+
+jobs:
+  build:
+    name: Build Jekyll Site
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: false
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: docs/vendor/bundle
+          key: ${{ runner.os }}-gems-${{ hashFiles('docs/Gemfile.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-gems-
+
+      - name: Install dependencies
+        run: |
+          cd docs
+          bundle config path vendor/bundle
+          bundle install --jobs 4 --retry 3
+
+      - name: Build Jekyll site
+        run: |
+          cd docs
+          bundle exec jekyll build --trace
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: docs/_site
+          retention-days: 7
+
+  link-check:
+    name: Check Links
+    runs-on: ubuntu-latest
+    needs: build
+    continue-on-error: true
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: site
+          path: docs/_site
+
+      - name: Install lychee
+        run: |
+          curl -sSL https://github.com/lycheeverse/lychee/releases/download/lychee-v0.22.0/lychee-x86_64-unknown-linux-gnu.tar.gz | tar -xz
+          sudo mv lychee /usr/local/bin/
+
+      - name: Run link checker
+        run: |
+          cd docs
+          lychee --config .lychee.toml _site --format markdown --output lychee-report.md
+        continue-on-error: true
+
+      - name: Display link check summary
+        if: always()
+        run: |
+          cd docs
+          if [ -f lychee-report.md ]; then
+            echo "## Link Check Results" >> $GITHUB_STEP_SUMMARY
+            cat lychee-report.md >> $GITHUB_STEP_SUMMARY
+          fi
+
+      - name: Check for broken links
+        run: |
+          cd docs
+          lychee --config .lychee.toml _site
+
+  validate-structure:
+    name: Validate Documentation Structure
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check for required files
+        run: |
+          cd docs
+          required_files=(
+            "index.adoc"
+            "README.md"
+            "_config.yml"
+            "Gemfile"
+            ".lychee.toml"
+          )
+          missing_files=()
+          for file in "${required_files[@]}"; do
+            if [ ! -f "$file" ]; then
+              missing_files+=("$file")
+            fi
+          done
+          if [ ${#missing_files[@]} -gt 0 ]; then
+            echo "Missing required files:"
+            printf '%s\n' "${missing_files[@]}"
+            exit 1
+          fi
+
+  summary:
+    name: Build Summary
+    runs-on: ubuntu-latest
+    needs: [build, link-check, validate-structure]
+    if: always()
+
+    steps:
+      - name: Generate summary
+        run: |
+          echo "## Documentation Build Summary" >> $GITHUB_STEP_SUMMARY
+          echo "Jekyll build completed" >> $GITHUB_STEP_SUMMARY
+          echo "Link validation completed" >> $GITHUB_STEP_SUMMARY
+          echo "Structure validation completed" >> $GITHUB_STEP_SUMMARY

data/docs/.gitignore

@@ -0,0 +1,21 @@
+# Jekyll build files
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+
+# Lychee cache
+.lycheecache
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Editor files
+*.swp
+*.swo
+*~
+
+# Ruby
+*.gem
+*.rbc

data/docs/.lychee.toml

@@ -0,0 +1,67 @@
+# Lychee link checker configuration for Omnizip documentation
+
+# Check all links recursively
+include_verbatim = false
+
+# Follow redirects
+max_redirects = 5
+
+# Timeout for requests (seconds)
+timeout = 30
+
+# Number of concurrent requests
+max_concurrency = 10
+
+# Accept HTTP status codes
+accept = [200, 201, 204, 206, 301, 302, 303, 304, 307, 308]
+
+# Retry failed requests
+max_retries = 3
+
+# User agent string
+user_agent = "lychee/omnizip-docs"
+
+# Exclude patterns (use regex syntax)
+exclude = [
+  # Exclude localhost and example URLs
+  "http://localhost.*",
+  "http://127\\.0\\.0\\.1.*",
+  "http://example\\.com.*",
+  "https://example\\.com.*",
+
+  # Exclude email addresses
+  "mailto:.*",
+
+  # Exclude same-page anchors (handled by Jekyll/AsciiDoc)
+  "^#.*",
+
+  # Exclude common placeholder URLs
+  "http://www\\.example\\.com.*",
+  "https://www\\.example\\.com.*",
+
+  # Exclude GitHub edit links (these are templates)
+  ".*/edit/.*",
+
+  # Exclude all internal site links - they work on deployed site
+  # but fail when checking local files due to baseurl path issues
+  "https?://metanorma\\.github\\.io/omnizip/.*",
+
+  # Exclude root-relative links with baseurl (local checking issue)
+  # These work when deployed but fail on local file system checks
+  "^/omnizip/.*"
+]
+
+# Cache responses to avoid repeated checks
+cache = true
+
+# Only check unique links
+no_progress = true
+
+# Check HTTPS certificates
+insecure = false
+
+# Scheme (http, https, file)
+scheme = ["https", "http"]
+
+# Don't fail on missing local files
+skip_missing = true

data/docs/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.4"
+gem "jekyll-asciidoc"
+gem "jekyll-seo-tag"
+gem "just-the-docs"
+
+group :jekyll_plugins do
+  gem "jekyll-feed"
+  gem "jekyll-sitemap"
+end

data/docs/RAR_WRITE_SUPPORT.md

@@ -0,0 +1,26 @@
+# RAR Write Support Documentation
+
+## Overview
+
+The key distinction:
+
+RAR format structure = Publicly documented, implementable ✅
+WinRAR's specific compression = Proprietary ❌
+
+## Important Licensing Information
+
+WinRAR is owned by Alexander Roshal and RARLAB. Creating RAR archives using WinRAR requires:
+
+1. **A valid WinRAR license** - Purchase from https://www.rarlab.com/
+2. **WinRAR installation** - The command-line tool must be installed
+
+RAR format structure = Publicly documented, implementable ✅
+WinRAR's specific compression = Proprietary ❌
+
+### Why Not Built-In?
+
+Unlike formats such as ZIP, 7z, TAR, etc., there is a confusion that RAR compression cannot be implemented freely due to:
+
+- Proprietary algorithm patents: but there are NO patents on RAR compression algorithms
+- Licensing restrictions from RARLAB: the RAR format structure is publicly documented, implementable, and already implemented independently in libarchive which is fully open source.
+- Legal risks of reverse engineering: the RAR format structure is documented and does not require reverse engineering.

data/docs/README.md

@@ -0,0 +1,101 @@
+# Omnizip Documentation
+
+This directory contains the documentation site for Omnizip, built with [Jekyll](https://jekyllrb.com/) and the [Just the Docs](https://just-the-docs.github.io/just-the-docs/) theme.
+
+## Building the Documentation Site
+
+### Prerequisites
+
+- Ruby 3.0 or higher
+- Bundler
+
+### Installation
+
+```bash
+cd docs
+bundle install
+```
+
+### Building
+
+```bash
+bundle exec jekyll build
+```
+
+The built site will be in the `_site` directory.
+
+### Serving Locally
+
+```bash
+bundle exec jekyll serve
+```
+
+Then open http://localhost:4000/omnizip/ in your browser.
+
+## Documentation Structure
+
+```
+docs/
+├── index.adoc                    # Home page
+├── getting-started/              # Installation and quick start guides
+├── guides/                       # Comprehensive usage guides
+│   ├── basic-usage/             # Basic operations
+│   ├── advanced-usage/          # Advanced features
+│   ├── compression-algorithms/  # Algorithm documentation
+│   ├── archive-formats/         # Format documentation
+│   └── filters/                 # Filter documentation
+├── reference/                    # Technical reference
+│   ├── cli/                     # CLI documentation
+│   └── api/                     # Ruby API documentation
+├── resources/                    # Additional resources
+├── concepts/                     # Core concepts
+├── developer/                    # Development documentation
+├── examples/                     # Usage examples
+└── troubleshooting/              # Troubleshooting guides
+```
+
+## Writing Documentation
+
+Documentation is written in [AsciiDoc](https://asciidoctor.org/) format. Each page should start with YAML front matter:
+
+```yaml
+---
+title: Page Title
+nav_order: 1
+---
+```
+
+### Linking
+
+Use AsciiDoc link syntax:
+
+- Internal link: `link:path/to/page.adoc[Link text]`
+- External link: `https://example.com[Link text]`
+
+### Code Blocks
+
+Use source code blocks with syntax highlighting:
+
+```asciidoc
+[source,ruby]
+----
+require 'omnizip'
+----
+```
+
+## Checking Links
+
+The documentation site includes a link checker using [lychee](https://github.com/lycheeverse/lychee). To check links:
+
+```bash
+# Install lychee
+cargo install lychee
+
+# Run link checker
+cd docs
+lychee --config .lychee.toml _site
+```
+
+## License
+
+Copyright 2025 Ribose Inc.