omnizip 0.3.1

data/docs/developer/architecture.adoc

@@ -0,0 +1,256 @@
+---
+title: Architecture
+nav_order: 90
+parent: Developer Guide
+---
+
+== Architecture
+
+Omnizip's system design and component relationships.
+
+=== Overview Diagram
+
+[source]
+----
+                    Omnizip Library
+                          |
+        +-----------------+-----------------+
+        |                 |                 |
+    Registries        Algorithms        Formats
+        |                 |                 |
+    +---+---+         +---+---+         +---+---+
+    |       |         |       |         |       |
+  Alg.   Filter   LZMA    BZip2      7z     ZIP
+  Reg.   Reg.     LZMA2   PPMd       RAR    TAR
+                    Deflate  Zstd      ISO    GZIP
+                                          CPIO   XZ
+                                            BZIP2
+----
+
+=== Registry Pattern
+
+All components use a registry pattern for extensibility:
+
+[source,ruby]
+----
+# Base registry class
+module Omnizip
+  class Registry
+    def initialize
+      @registry = {}
+    end
+
+    def register(name, klass)
+      @registry[name] = klass
+    end
+
+    def get(name)
+      @registry[name] || raise(NotFoundError, name)
+    end
+
+    def registered
+      @registry.keys
+    end
+  end
+end
+
+# Algorithm registry
+AlgorithmRegistry = Registry.new
+
+# Filter registry
+FilterRegistry = Registry.new
+
+# Format registry
+FormatRegistry = Registry.new
+----
+
+=== Algorithm Architecture
+
+Compression algorithms implement a common interface:
+
+[source,ruby]
+----
+module Omnizip
+  module Algorithms
+    class Base
+      def initialize(options = {})
+        @options = options
+      end
+
+      def compress(input, output)
+        raise NotImplementedError
+      end
+
+      def decompress(input, output)
+        raise NotImplementedError
+      end
+    end
+  end
+end
+
+# Example: LZMA2
+module Algorithms
+  class LZMA2 < Base
+    def compress(input, output)
+      # LZMA2 compression implementation
+    end
+
+    def decompress(input, output)
+      # LZMA2 decompression implementation
+    end
+  end
+end
+----
+
+=== Format Architecture
+
+Archive formats implement reader/writer interfaces:
+
+[source,ruby]
+----
+module Omnizip
+  module Formats
+    module SevenZip
+      class Reader
+        def initialize(filename)
+          @filename = filename
+        end
+
+        def open
+          # Open archive
+        end
+
+        def each_file
+          # Yield archive entries
+        end
+
+        def extract_all(output_dir)
+          # Extract all files
+        end
+
+        def close
+          # Close archive
+        end
+      end
+
+      class Writer
+        def initialize(filename, options = {})
+          @filename = filename
+          @options = options
+        end
+
+        def add_file(path)
+          # Add file to archive
+        end
+
+        def add_directory(path)
+          # Add directory to archive
+        end
+
+        def close
+          # Write and close archive
+        end
+      end
+    end
+  end
+end
+----
+
+=== Component Relationships
+
+==== Compression Flow
+
+[source,ruby]
+----
+# User API call
+Omnizip.compress_file('input.txt', 'output.lzma',
+  algorithm: :lzma2,
+  level: 9
+)
+
+# Resolves to:
+# 1. Get algorithm from registry
+algorithm = AlgorithmRegistry.get(:lzma2).new(level: 9)
+
+# 2. Open files
+File.open('input.txt', 'rb') do |input|
+  File.open('output.lzma', 'wb') do |output|
+    # 3. Compress
+    algorithm.compress(input, output)
+  end
+end
+----
+
+==== Archive Creation Flow
+
+[source,ruby]
+----
+# User API call
+writer = Formats::SevenZip::Writer.new('archive.7z',
+  algorithm: :lzma2,
+  level: 7
+)
+
+# Resolves to:
+# 1. Get algorithm
+algorithm = AlgorithmRegistry.get(:lzma2).new(level: 7)
+
+# 2. Apply filters (if any)
+filters = options[:filters].map do |name|
+  FilterRegistry.get(name).new
+end
+
+# 3. For each added file:
+#    a. Apply filters
+#    b. Compress with algorithm
+#    c. Write to archive
+
+writer.add_file('document.txt')
+writer.close
+----
+
+### Design Principles
+
+==== Object-Oriented
+
+All components use proper OOP:
+
+* Encapsulation of state and behavior
+* Inheritance for shared functionality
+* Polymorphism for extensibility
+
+==== Separation of Concerns
+
+Each component has single responsibility:
+
+* **Algorithms** - Compression/decompression only
+* **Formats** - Archive structure only
+* **Filters** - Preprocessing only
+* **Checksums** - Integrity verification only
+
+==== Extensibility
+
+Easy to add new components:
+
+[source,ruby]
+----
+# Add custom algorithm
+class MyAlgorithm < Omnizip::Algorithms::Base
+  def compress(input, output)
+    # Custom compression
+  end
+end
+
+Omnizip::AlgorithmRegistry.register(:myalgo, MyAlgorithm)
+
+# Use immediately
+Omnizip.compress_file('input.txt', 'output.my',
+  algorithm: :myalgo
+)
+----
+
+### See Also
+
+* link:../concepts/[Core Concepts]
+* link:contributing[Contributing Guide]
+* link:../guides/[Usage Guides]

data/docs/developer/contributing.adoc

@@ -0,0 +1,158 @@
+---
+title: Contributing
+nav_order: 86
+parent: Developer Guide
+---
+
+== Contributing
+
+Thank you for considering contributing to Omnizip!
+
+=== General
+
+Contributions are welcome! This document provides guidelines for contributing to Omnizip.
+
+=== Code of Conduct
+
+* Be respectful and inclusive
+* Provide constructive feedback
+* Focus on what is best for the community
+
+### How to Contribute
+
+==== Report Bugs
+
+Report bugs at https://github.com/metanorma/omnizip/issues
+
+Include:
+
+* Omnizip version
+* Ruby version
+* Operating system
+* Reproduction steps
+* Expected vs actual behavior
+
+==== Suggest Features
+
+Request features at https://github.com/metanorma/omnizip/issues
+
+Explain:
+
+* Use case for the feature
+* Why it's important
+* Proposed implementation (if known)
+
+==== Submit Pull Requests
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add/update tests
+5. Run test suite
+6. Run linter
+7. Commit with semantic message
+8. Push to branch
+9. Create pull request
+
+=== Development Setup
+
+[source,bash]
+----
+# Clone repository
+git clone https://github.com/metanorma/omnizip.git
+cd omnizip
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop -A
+----
+
+### Coding Standards
+
+==== Style Guide
+
+Follow these guidelines:
+
+* Use 2 spaces for indentation
+* Max line length: 80 characters
+* Max method length: 50 lines
+* Max class length: 700 lines
+
+==== Naming Conventions
+
+* Classes: `PascalCase`
+* Methods: `snake_case`
+* Constants: `SCREAMING_SNAKE_CASE`
+* Variables: `snake_case`
+
+==== Documentation
+
+* Document public methods with YARD comments
+* Include usage examples
+* Explain parameters and return values
+
+=== Testing
+
+==== Test Coverage
+
+Aim for:
+
+* Unit tests for all methods
+* Integration tests for formats
+* Round-trip tests for compression
+
+==== Test Structure
+
+[source,ruby]
+----
+RSpec.describe Omnizip::Algorithms::LZMA do
+  describe '#compress' do
+    it 'compresses data correctly' do
+      # Test implementation
+    end
+  end
+
+  describe '#decompress' do
+    it 'decompresses data correctly' do
+      # Test implementation
+    end
+  end
+end
+----
+
+=== Commit Messages
+
+Use semantic commit messages:
+
+```
+feat(algorithm): add new compression algorithm
+fix(format): correct ZIP file header parsing
+docs(guide): update installation instructions
+test(spec): add regression test for issue #123
+```
+
+### Release Process
+
+Releases are managed by maintainers:
+
+1. Update version number
+2. Update CHANGELOG
+3. Create release tag
+4. Build and publish gem
+5. Update documentation
+
+### Getting Help
+
+* GitHub Issues: https://github.com/metanorma/omnizip/issues
+* Discussions: https://github.com/metanorma/omnizip/discussions
+
+### See Also
+
+* link:code-style[Code Style] - Detailed coding standards
+* link:testing[Testing Guide] - Testing guidelines
+* link:architecture[Architecture] - System design

data/docs/developer/index.adoc

@@ -0,0 +1,25 @@
+---
+title: Developer Guide
+nav_order: 85
+has_children: true
+---
+
+== Developer Guide
+
+Information for developers contributing to or extending Omnizip.
+
+=== Contributing
+
+* link:contributing[Contributing Guide] - How to contribute
+* link:code-style[Code Style] - Coding standards
+* link:testing[Testing] - Running and writing tests
+
+=== Development
+
+* link:architecture[Architecture] - System design and patterns
+* link:release-process[Release Process] - How releases work
+
+=== Resources
+
+* link:../concepts/[Core Concepts] - Fundamental concepts
+* link:../troubleshooting/[Troubleshooting] - Common issues

data/docs/developer/testing.adoc

@@ -0,0 +1,212 @@
+---
+title: Testing
+nav_order: 88
+parent: Developer Guide
+---
+
+== Testing
+
+Guidelines for running and writing tests for Omnizip.
+
+=== Running Tests
+
+==== Run All Tests
+
+[source,bash]
+----
+bundle exec rspec
+----
+
+==== Run Specific Test File
+
+[source,bash]
+----
+bundle exec rspec spec/omnizip/algorithms/lzma_spec.rb
+----
+
+==== Run with Documentation Format
+
+[source,bash]
+----
+bundle exec rspec --format documentation
+----
+
+==== Run with Coverage
+
+[source,bash]
+----
+bundle exec rspec --format documentation --format html --out coverage.html
+----
+
+=== Writing Tests
+
+==== Test Structure
+
+[source,ruby]
+----
+RSpec.describe Omnizip::Algorithms::LZMA do
+  let(:algorithm) { described_class.new(level: 5) }
+
+  describe '#compress' do
+    it 'compresses data' do
+      input = StringIO.new('Hello, World!')
+      output = StringIO.new
+
+      algorithm.compress(input, output)
+
+      expect(output.string).to start_with LZMA_MAGIC_BYTES
+    end
+  end
+
+  describe '#decompress' do
+    it 'decompresses data' do
+      # Test implementation
+    end
+  end
+end
+----
+
+==== Test Fixtures
+
+Place test fixtures in `spec/fixtures/`:
+
+```
+spec/fixtures/
+├── compression/
+│   ├── test.txt
+│   ├── test.txt.lzma
+│   └── test.txt.bz2
+└── archives/
+    ├── test.7z
+    ├── test.zip
+    └── test.rar
+----
+
+==== Use StringIO for File Tests
+
+[source,ruby]
+----
+# Instead of real files
+input = StringIO.new('test data')
+output = StringIO.new
+
+algorithm.compress(input, output)
+
+expect(output.string).to eq compressed_data
+----
+
+=== Test Coverage
+
+==== Unit Tests
+
+Test individual methods and classes:
+
+[source,ruby]
+----
+RSpec.describe Omnizip::AlgorithmRegistry do
+  describe '#get' do
+    it 'returns algorithm instance' do
+      algorithm = Omnizip::AlgorithmRegistry.get(:lzma2)
+      expect(algorithm).to be_a(Omnizip::Algorithms::LZMA2)
+    end
+  end
+end
+----
+
+==== Integration Tests
+
+Test complete workflows:
+
+[source,ruby]
+----
+RSpec.describe 'LZMA2 compression workflow' do
+  it 'compresses and decompresses file' do
+    # Compress
+    Omnizip.compress_file('input.txt', 'output.lzma')
+
+    # Decompress
+    Omnizip.decompress_file('output.lzma', 'restored.txt')
+
+    # Verify
+    expect(File.read('restored.txt')).to eq File.read('input.txt')
+  end
+end
+----
+
+=== Best Practices
+
+==== Isolation
+
+Each test should be independent:
+
+[source,ruby]
+----
+# Good
+RSpec.describe 'File compression' do
+  let(:temp_dir) { Dir.mktmpdir }
+  let(:input_file) { File.join(temp_dir, 'input.txt') }
+  let(:output_file) { File.join(temp_dir, 'output.lzma') }
+
+  before do
+    File.write(input_file, 'test data')
+  end
+
+  after do
+    FileUtils.rm_rf(temp_dir)
+  end
+
+  it 'compresses file' do
+    Omnizip.compress_file(input_file, output_file)
+    expect(File.exist?(output_file)).to be true
+  end
+end
+----
+
+==== Descriptive Names
+
+Use descriptive test names:
+
+[source,ruby]
+----
+# Good
+it 'compresses text file with 50% ratio'
+
+# Bad
+it 'works'
+----
+
+==== No Mocks
+
+Prefer real behavior over mocks:
+
+[source,ruby]
+----
+# Good
+it 'compresses data' do
+  algorithm = LZMA2.new(level: 5)
+  input = StringIO.new('test')
+  output = StringIO.new
+
+  algorithm.compress(input, output)
+
+  expect(output.string.length).to be < input.string.length
+end
+
+# Avoid
+it 'compresses data' do
+  allow(algorithm).to receive(:compress).and_return('result')
+end
+----
+
+=== CI/CD
+
+Tests run automatically on:
+
+* Pull requests
+* Push to main branch
+* Scheduled runs
+
+### See Also
+
+* link:../troubleshooting/[Troubleshooting]
+* link:architecture[Architecture]