omnizip 0.3.1

data/lib/omnizip/metadata/archive_metadata.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Metadata
+    # Model for archive-level metadata
+    class ArchiveMetadata
+      attr_reader :archive
+
+      # Initialize archive metadata
+      # @param archive [Omnizip::Zip::File] The archive to manage metadata for
+      def initialize(archive)
+        @archive = archive
+        @modified = false
+      end
+
+      # Get archive comment
+      # @return [String] Archive comment
+      def comment
+        archive.comment
+      end
+
+      # Set archive comment
+      # @param value [String] New comment
+      def comment=(value)
+        archive.comment = value.to_s
+        @modified = true
+      end
+
+      # Get creation date (approximated from first entry)
+      # @return [Time, nil] Creation date or nil
+      def created_at
+        return nil if archive.entries.empty?
+
+        archive.entries.map(&:time).min
+      end
+
+      # Get modification date (from newest entry)
+      # @return [Time, nil] Modification date or nil
+      def modified_at
+        return nil if archive.entries.empty?
+
+        archive.entries.map(&:time).max
+      end
+
+      # Get total uncompressed size
+      # @return [Integer] Total uncompressed size in bytes
+      def total_size
+        archive.entries.sum(&:size)
+      end
+
+      # Get total compressed size
+      # @return [Integer] Total compressed size in bytes
+      def total_compressed_size
+        archive.entries.sum(&:compressed_size)
+      end
+
+      # Get compression ratio
+      # @return [Float] Compression ratio (0.0 to 1.0)
+      def compression_ratio
+        return 0.0 if total_size.zero?
+
+        ratio = 1.0 - (total_compressed_size.to_f / total_size)
+        # Clamp ratio between 0.0 and 1.0 (compressed size can exceed
+        # original size for small files or incompressible data)
+        [[ratio, 0.0].max, 1.0].min
+      end
+
+      # Get entry count
+      # @return [Integer] Number of entries
+      def entry_count
+        archive.entries.size
+      end
+
+      # Get file count (excluding directories)
+      # @return [Integer] Number of files
+      def file_count
+        archive.entries.count(&:file?)
+      end
+
+      # Get directory count
+      # @return [Integer] Number of directories
+      def directory_count
+        archive.entries.count(&:directory?)
+      end
+
+      # Check if metadata has been modified
+      # @return [Boolean] True if modified
+      def modified?
+        @modified
+      end
+
+      # Reset modified flag
+      def reset_modified
+        @modified = false
+      end
+
+      # Get all metadata as a hash
+      # @return [Hash] Metadata hash
+      def to_h
+        {
+          comment: comment,
+          created_at: created_at,
+          modified_at: modified_at,
+          total_size: total_size,
+          total_compressed_size: total_compressed_size,
+          compression_ratio: compression_ratio,
+          entry_count: entry_count,
+          file_count: file_count,
+          directory_count: directory_count,
+        }
+      end
+    end
+  end
+end

data/lib/omnizip/metadata/entry_metadata.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Metadata
+    # Model for file entry metadata
+    # Wraps CentralDirectoryHeader with a cleaner metadata API
+    class EntryMetadata
+      attr_reader :entry
+
+      # Initialize metadata for an entry
+      # @param entry [Omnizip::Zip::Entry] The entry to manage metadata for
+      def initialize(entry)
+        @entry = entry
+        @modified = false
+      end
+
+      # Get entry comment
+      # @return [String] Entry comment
+      def comment
+        entry.comment
+      end
+
+      # Set entry comment
+      # @param value [String] New comment
+      def comment=(value)
+        entry.comment = value.to_s
+        @modified = true
+      end
+
+      # Get modification time
+      # @return [Time] Modification time
+      def mtime
+        entry.time
+      end
+
+      # Set modification time
+      # @param value [Time] New modification time
+      def mtime=(value)
+        unless value.is_a?(Time)
+          raise ArgumentError,
+                "mtime must be a Time object"
+        end
+
+        entry.header.last_mod_time = dos_time(value)
+        entry.header.last_mod_date = dos_date(value)
+        @modified = true
+      end
+
+      # Get Unix permissions
+      # @return [Integer] Unix permissions (e.g., 0644)
+      def unix_permissions
+        entry.unix_perms
+      end
+
+      # Set Unix permissions
+      # @param perms [Integer] Unix permissions (e.g., 0644, 0755)
+      def unix_permissions=(perms)
+        unless perms.is_a?(Integer)
+          raise ArgumentError,
+                "permissions must be an integer"
+        end
+        unless (0..0o777).cover?(perms)
+          raise ArgumentError,
+                "permissions out of range"
+        end
+
+        entry.unix_perms = perms
+        @modified = true
+      end
+
+      # Get external attributes
+      # @return [Integer] External attributes
+      def attributes
+        entry.header.external_attributes
+      end
+
+      # Set external attributes
+      # @param value [Integer, Symbol] External attributes or symbol like :readonly
+      def attributes=(value)
+        case value
+        when Integer
+          entry.header.external_attributes = value
+        when Symbol
+          set_attribute_flag(value)
+        else
+          raise ArgumentError, "attributes must be Integer or Symbol"
+        end
+        @modified = true
+      end
+
+      # Check if metadata has been modified
+      # @return [Boolean] True if modified
+      def modified?
+        @modified
+      end
+
+      # Reset modified flag
+      def reset_modified
+        @modified = false
+      end
+
+      # Get all metadata as a hash
+      # @return [Hash] Metadata hash
+      def to_h
+        {
+          name: entry.name,
+          comment: comment,
+          mtime: mtime,
+          unix_permissions: unix_permissions,
+          size: entry.size,
+          compressed_size: entry.compressed_size,
+          crc: entry.crc,
+          directory: entry.directory?,
+        }
+      end
+
+      private
+
+      # Set attribute flag
+      def set_attribute_flag(flag)
+        case flag
+        when :readonly
+          entry.header.external_attributes |= 0x01
+        when :hidden
+          entry.header.external_attributes |= 0x02
+        when :system
+          entry.header.external_attributes |= 0x04
+        when :archive
+          entry.header.external_attributes |= 0x20
+        else
+          raise ArgumentError, "Unknown attribute flag: #{flag}"
+        end
+      end
+
+      # Convert Time to DOS time format
+      def dos_time(time)
+        ((time.hour << 11) | (time.min << 5) | (time.sec / 2)) & 0xFFFF
+      end
+
+      # Convert Time to DOS date format
+      def dos_date(time)
+        (((time.year - 1980) << 9) | (time.month << 5) | time.day) & 0xFFFF
+      end
+    end
+  end
+end

data/lib/omnizip/metadata/metadata_editor.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "metadata_validator"
+
+module Omnizip
+  module Metadata
+    # Coordinates metadata editing operations
+    class MetadataEditor
+      attr_reader :archive, :validator
+
+      # Initialize metadata editor
+      # @param archive [Omnizip::Zip::File] Archive to edit
+      def initialize(archive)
+        @archive = archive
+        @validator = MetadataValidator.new
+        @changes = []
+      end
+
+      # Set timestamps for all entries
+      # @param time [Time] Time to set
+      # @param filter [Proc] Optional filter to select entries
+      def set_all_timestamps(time, &filter)
+        validator.validate_time(time)
+
+        entries = filter ? archive.entries.select(&filter) : archive.entries
+
+        entries.each do |entry|
+          next if entry.directory?
+
+          metadata = EntryMetadata.new(entry)
+          metadata.mtime = time
+          @changes << { entry: entry, field: :mtime, value: time }
+        end
+
+        self
+      end
+
+      # Normalize permissions (set sensible defaults)
+      # @param file_perms [Integer] Permissions for files (default: 0644)
+      # @param dir_perms [Integer] Permissions for directories (default: 0755)
+      def normalize_permissions(file_perms: 0o644, dir_perms: 0o755)
+        validator.validate_permissions(file_perms)
+        validator.validate_permissions(dir_perms)
+
+        archive.entries.each do |entry|
+          metadata = EntryMetadata.new(entry)
+          perms = entry.directory? ? dir_perms : file_perms
+          metadata.unix_permissions = perms
+          @changes << { entry: entry, field: :permissions, value: perms }
+        end
+
+        self
+      end
+
+      # Strip all comments from entries and archive
+      def strip_comments
+        archive.entries.each do |entry|
+          metadata = EntryMetadata.new(entry)
+          metadata.comment = ""
+          @changes << { entry: entry, field: :comment, value: "" }
+        end
+
+        archive.comment = ""
+        @changes << { entry: :archive, field: :comment, value: "" }
+
+        self
+      end
+
+      # Set comment for entries matching a pattern
+      # @param pattern [String, Regexp] Pattern to match
+      # @param comment [String] Comment to set
+      def set_comment_matching(pattern, comment)
+        validator.validate_comment(comment)
+
+        matching_entries = if pattern.is_a?(Regexp)
+                             archive.entries.select { |e| e.name =~ pattern }
+                           else
+                             archive.entries.select do |e|
+                               ::File.fnmatch(pattern, e.name)
+                             end
+                           end
+
+        matching_entries.each do |entry|
+          metadata = EntryMetadata.new(entry)
+          metadata.comment = comment
+          @changes << { entry: entry, field: :comment, value: comment }
+        end
+
+        self
+      end
+
+      # Set permissions for entries matching a pattern
+      # @param pattern [String, Regexp] Pattern to match
+      # @param perms [Integer] Permissions to set
+      def set_permissions_matching(pattern, perms)
+        validator.validate_permissions(perms)
+
+        matching_entries = if pattern.is_a?(Regexp)
+                             archive.entries.select { |e| e.name =~ pattern }
+                           else
+                             archive.entries.select do |e|
+                               ::File.fnmatch(pattern, e.name)
+                             end
+                           end
+
+        matching_entries.each do |entry|
+          next if entry.directory?
+
+          metadata = EntryMetadata.new(entry)
+          metadata.unix_permissions = perms
+          @changes << { entry: entry, field: :permissions, value: perms }
+        end
+
+        self
+      end
+
+      # Update timestamps to preserve relative ordering
+      # Useful for maintaining build timestamps while updating absolute times
+      # @param base_time [Time] Base time for earliest file
+      def preserve_relative_timestamps(base_time = Time.now)
+        validator.validate_time(base_time)
+
+        # Find earliest timestamp
+        earliest = archive.entries.map(&:time).min
+        return self unless earliest
+
+        # Calculate offset
+        offset = base_time.to_i - earliest.to_i
+
+        archive.entries.each do |entry|
+          next if entry.directory?
+
+          new_time = Time.at(entry.time.to_i + offset)
+          metadata = EntryMetadata.new(entry)
+          metadata.mtime = new_time
+          @changes << { entry: entry, field: :mtime, value: new_time }
+        end
+
+        self
+      end
+
+      # Get list of pending changes
+      # @return [Array<Hash>] List of changes
+      def pending_changes
+        @changes
+      end
+
+      # Check if there are pending changes
+      # @return [Boolean] True if there are changes
+      def modified?
+        !@changes.empty?
+      end
+
+      # Clear pending changes
+      def clear_changes
+        @changes = []
+        self
+      end
+
+      # Commit all changes to archive
+      # This marks the archive as modified and saves on close
+      def commit
+        # Changes are already applied to entries
+        # Just mark archive as modified
+        archive.instance_variable_set(:@modified, true) if modified?
+        @changes = []
+        self
+      end
+    end
+  end
+end

data/lib/omnizip/metadata/metadata_registry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Metadata
+    # Registry of supported metadata per archive format
+    class MetadataRegistry
+      @registry = {}
+
+      class << self
+        # Register metadata support for a format
+        # @param format [Symbol] Format name (e.g., :zip, :seven_zip)
+        # @param supported_fields [Array<Symbol>] Supported metadata fields
+        def register(format, supported_fields)
+          @registry[format] = supported_fields
+        end
+
+        # Check if a format supports a metadata field
+        # @param format [Symbol] Format name
+        # @param field [Symbol] Metadata field name
+        # @return [Boolean] True if supported
+        def supports?(format, field)
+          fields = @registry[format]
+          return false unless fields
+
+          fields.include?(field)
+        end
+
+        # Get all supported fields for a format
+        # @param format [Symbol] Format name
+        # @return [Array<Symbol>] List of supported fields
+        def supported_fields(format)
+          @registry[format] || []
+        end
+
+        # Get all registered formats
+        # @return [Array<Symbol>] List of formats
+        def formats
+          @registry.keys
+        end
+
+        # Reset registry (for testing)
+        def reset
+          @registry = {}
+        end
+      end
+    end
+
+    # Register ZIP format metadata support
+    MetadataRegistry.register(:zip, %i[
+                                comment
+                                mtime
+                                unix_permissions
+                                external_attributes
+                                filename
+                                extra_field
+                              ])
+
+    # Register 7z format metadata support (limited)
+    MetadataRegistry.register(:seven_zip, %i[
+                                mtime
+                                attributes
+                              ])
+  end
+end

data/lib/omnizip/metadata/metadata_validator.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Metadata
+    # Validates metadata changes before applying
+    class MetadataValidator
+      # Validate entry metadata
+      # @param metadata [EntryMetadata] Metadata to validate
+      # @raise [ArgumentError] If metadata is invalid
+      def validate_entry(metadata)
+        validate_comment(metadata.comment) if metadata.comment
+        validate_time(metadata.mtime) if metadata.respond_to?(:mtime)
+        validate_permissions(metadata.unix_permissions) if metadata.unix_permissions
+
+        true
+      end
+
+      # Validate archive metadata
+      # @param metadata [ArchiveMetadata] Metadata to validate
+      # @raise [ArgumentError] If metadata is invalid
+      def validate_archive(metadata)
+        validate_comment(metadata.comment) if metadata.comment
+
+        true
+      end
+
+      # Validate comment length
+      # @param comment [String] Comment to validate
+      # @raise [ArgumentError] If comment is too long
+      def validate_comment(comment)
+        max_length = 65_535 # ZIP format limit
+        return true if comment.bytesize <= max_length
+
+        raise ArgumentError,
+              "Comment too long: #{comment.bytesize} bytes (max: #{max_length})"
+      end
+
+      # Validate time value
+      # @param time [Time] Time to validate
+      # @raise [ArgumentError] If time is invalid
+      def validate_time(time)
+        return true unless time
+
+        unless time.is_a?(Time)
+          raise ArgumentError, "Time must be a Time object, got #{time.class}"
+        end
+
+        # DOS time range: 1980-01-01 to 2107-12-31
+        min_time = Time.new(1980, 1, 1)
+        max_time = Time.new(2107, 12, 31, 23, 59, 59)
+
+        if time < min_time || time > max_time
+          raise ArgumentError, "Time out of DOS range (1980-2107): #{time}"
+        end
+
+        true
+      end
+
+      # Validate Unix permissions
+      # @param perms [Integer] Permissions to validate
+      # @raise [ArgumentError] If permissions are invalid
+      def validate_permissions(perms)
+        return true unless perms
+
+        unless perms.is_a?(Integer)
+          raise ArgumentError,
+                "Permissions must be an integer, got #{perms.class}"
+        end
+
+        unless (0..0o777).cover?(perms)
+          raise ArgumentError,
+                "Permissions out of range: 0#{perms.to_s(8)} (max: 0777)"
+        end
+
+        true
+      end
+
+      # Validate filename
+      # @param filename [String] Filename to validate
+      # @raise [ArgumentError] If filename is invalid
+      def validate_filename(filename)
+        return true unless filename
+
+        max_length = 65_535 # ZIP format limit
+        if filename.bytesize > max_length
+          raise ArgumentError,
+                "Filename too long: #{filename.bytesize} bytes (max: #{max_length})"
+        end
+
+        # Check for invalid characters
+        if filename.include?("\x00")
+          raise ArgumentError, "Filename contains null character"
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/omnizip/metadata.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "metadata/entry_metadata"
+require_relative "metadata/archive_metadata"
+require_relative "metadata/metadata_validator"
+require_relative "metadata/metadata_registry"
+require_relative "metadata/metadata_editor"
+
+module Omnizip
+  # Metadata editing module
+  # Provides in-place metadata modification without recompression
+  module Metadata
+    class << self
+      # Edit entry metadata
+      # @param entry [Omnizip::Zip::Entry] Entry to edit
+      # @yield [metadata] Block to modify metadata
+      # @return [EntryMetadata] Entry metadata object
+      def edit_entry(entry, &block)
+        metadata = EntryMetadata.new(entry)
+        yield(metadata) if block
+        metadata
+      end
+
+      # Edit archive metadata
+      # @param archive [Omnizip::Zip::File] Archive to edit
+      # @yield [metadata] Block to modify metadata
+      # @return [ArchiveMetadata] Archive metadata object
+      def edit_archive(archive, &block)
+        metadata = ArchiveMetadata.new(archive)
+        yield(metadata) if block
+        metadata
+      end
+
+      # Create a metadata editor for batch operations
+      # @param archive [Omnizip::Zip::File] Archive to edit
+      # @return [MetadataEditor] Metadata editor
+      def editor(archive)
+        MetadataEditor.new(archive)
+      end
+
+      # Validate metadata
+      # @param metadata [EntryMetadata, ArchiveMetadata] Metadata to validate
+      # @return [Boolean] True if valid
+      def validate(metadata)
+        validator = MetadataValidator.new
+        case metadata
+        when EntryMetadata
+          validator.validate_entry(metadata)
+        when ArchiveMetadata
+          validator.validate_archive(metadata)
+        else
+          raise ArgumentError, "Unknown metadata type: #{metadata.class}"
+        end
+      end
+    end
+  end
+end