comicinfo 1.0.0

data/doc/development.md

@@ -0,0 +1,255 @@
+# Development Guidelines
+
+## Project Overview
+This Ruby gem provides an idiomatic interface for working with ComicInfo.xml files,
+following the official ComicInfo schema specifications from the Anansi Project.
+
+## Development Philosophy
+- **Test-Driven Development**: Write failing tests first, then implement functionality
+- **Idiomatic Ruby**: Follow Ruby conventions and best practices
+- **Schema Compliance**: Strict adherence to ComicInfo XSD schema definitions
+- **Error Handling**: Graceful handling of malformed XML and invalid data
+
+## Code Standards
+
+### Ruby Version
+- Minimum required: Ruby 3.4.6+
+- Use modern Ruby features and syntax patterns
+
+### Dependencies
+- **nokogiri** (>= 1.18.10): XML parsing and generation
+- **rspec** (>= 3.13.1): Testing framework
+- **rubocop** (>= 1.81.1): Code linting and formatting
+
+### Code Style
+- Follow RuboCop rules (configured in `.rubocop.yml`)
+- Use 2-space indentation
+
+### Testing Guidelines
+- Use RSpec for all tests
+- Create fixture files for test data (no inline XML strings)
+- Test both happy path and error conditions
+- Aim for >95% test coverage
+- Group related tests in describe/context blocks
+- Use descriptive test descriptions
+- **Code Alignment**: Align similar parts of lines only within the same method or `it` block
+- **Test Structure**: Align expect statements within individual test cases for readability
+
+### File Organization
+```
+lib/
+├─ comicinfo.rb                # Main module and autoloads
+├─ comicinfo/
+│   ├─ version.rb             # Gem version constant
+│   ├─ issue.rb               # Main ComicInfo::Issue class
+│   ├─ page.rb                # ComicInfo::Page class
+│   ├─ enums.rb               # Schema enum definitions
+│   └─ errors.rb              # Custom exception classes
+spec/
+├─ spec_helper.rb              # RSpec configuration with FixtureHelpers
+├─ comic_info_spec.rb          # Main module specs
+├─ comic_info/
+│   ├─ issue_spec.rb          # ComicInfo::Issue class specs
+│   └─ page_spec.rb           # ComicInfo::Page class specs
+└─ fixtures/                   # XML test fixtures
+│       ├─ valid_minimal.xml
+│       ├─ valid_complete.xml
+│       ├─ invalid_xml.xml
+│       └─ edge_cases/
+```
+
+## API Design Principles
+
+### Class Interface
+```ruby
+# Primary interface
+ComicInfo.load file_path_or_xml_string #=> ComicInfo::Issue instance
+ComicInfo::Issue.new xml_string        #=> ComicInfo::Issue instance
+
+# Instance methods match schema fields
+comic.title  #=> String
+comic.series #=> String
+comic.count  #=> Integer
+comic.pages  #=> Array<ComicInfo::Page>
+comic.black_and_white #=> String (enum value)
+
+# Multi-value fields have both singular and plural methods
+comic.character  #=> String (comma-separated)
+comic.characters #=> Array<String>
+comic.genre      #=> String (comma-separated)
+comic.genres     #=> Array<String>
+comic.web        #=> String (space-separated URLs)
+comic.web_urls   #=> Array<String>
+```
+
+### Naming Conventions
+- Class names: `ComicInfo::Issue`, `ComicInfo::Page`
+- Method names: snake_case following Ruby conventions
+- Schema field mapping:
+  - XML `<Title>` → Ruby `#title`
+  - XML `<BlackAndWhite>` → Ruby `#black_and_white`
+  - XML `<CommunityRating>` → Ruby `#community_rating`
+- Multi-value fields:
+  - Singular method returns original string from XML
+  - Plural method returns array of split values
+  - XML `<Characters>` → Ruby `#character` (string) & `#characters` (array)
+  - XML `<Teams>` → Ruby `#team` (string) & `#teams` (array)
+
+### Error Handling
+- Define custom exception classes in `ComicInfo::Errors`
+- Validate enum values against schema definitions
+- Provide meaningful error messages for invalid data
+- Handle XML parsing errors gracefully
+
+## Development Workflow
+
+### Development Process
+1. Write failing tests with fixture files
+2. Implement minimal code to make tests pass
+3. Refactor for clarity and performance
+4. Run RuboCop to ensure code style compliance
+5. Verify all tests pass
+6. Update documentation if needed
+
+### Before Committing
+```sh
+# Run linter (must pass)
+bundle exec rubocop
+
+# Run tests (must all pass)
+bundle exec rspec
+
+# Check test coverage
+bundle exec rspec --format documentation
+```
+
+### Commit Standards
+- Never commit failing tests
+- Mark unimplemented tests as `skip` or `pending`
+- Use descriptive commit messages
+- Keep commits focused and atomic
+
+## Schema Implementation Notes
+
+### Enum Handling
+- Validate all enum values against XSD schema
+- Provide constants for valid enum values
+- Return original string values, not symbols
+
+### Multi-value Fields
+- Handle comma-separated values in fields like Genre, Characters
+- Provide both string and array access methods
+- Preserve original formatting when possible
+
+### Type Coercion
+- String fields: preserve as-is from XML
+- Integer fields: convert with proper error handling
+- Decimal fields: use BigDecimal for precision
+- Boolean attributes: handle "true"/"false" strings
+
+### Default Values
+- Follow XSD schema default values
+- Empty strings for string fields
+- -1 for unset integer fields
+- "Unknown" for enum fields where applicable
+
+## Testing Strategy
+
+### Fixture Files
+Create comprehensive XML fixtures covering:
+- Minimal valid ComicInfo.xml (required fields only)
+- Complete ComicInfo.xml (all fields populated)
+- Invalid XML (malformed syntax)
+- Invalid data (enum violations, out-of-range values)
+- Edge cases (special characters, Unicode, empty elements)
+
+### Test Categories
+1. **Unit tests**: Individual method behavior
+2. **Integration tests**: Full XML parsing workflows
+3. **Error handling tests**: Invalid inputs and edge cases
+4. **Fixture helpers**: Centralized test data management
+
+### Test Organization
+```ruby
+RSpec.describe ComicInfo::Issue do
+  describe '.load' do
+    context 'with valid file path' do
+      it 'loads from fixture' do
+        comic = load_fixture 'valid_minimal.xml'
+
+        expect(comic).to be_a described_class
+
+        expect(comic.title).to  eq 'Expected Title'
+        expect(comic.series).to eq 'Expected Series'
+        expect(comic.number).to eq '1'
+      end
+    end
+
+    context 'with XML string' do
+      it 'parses XML content' do
+        xml_content = fixture_file 'valid_complete.xml'
+        comic = described_class.new xml_content
+
+        expect(comic).to be_a described_class
+        expect(comic.series).to eq 'Expected Series'
+      end
+    end
+  end
+
+  describe 'multi-value fields' do
+    describe 'singular methods (return strings)' do
+      it 'returns character as comma-separated string' do
+        expect(complete_comic.character).to eq 'Spider-Man, Peter Parker'
+      end
+    end
+
+    describe 'plural methods (return arrays)' do
+      it 'returns characters as array' do
+        expect(complete_comic.characters).to eq ['Spider-Man', 'Peter Parker']
+      end
+    end
+  end
+end
+```
+
+## Performance Considerations
+- Use Nokogiri’s XML parsing with CSS selectors
+- ComicInfo.xml files are typically small (<100KB)
+- Focus on code clarity over micro-optimizations
+
+## Code Quality Standards
+
+### Test Code Formatting
+- **Alignment Scope**: Only align similar parts of lines within the same method or `it` block
+- **Good Example**: Align multiple expect statements within one test case
+- **Bad Example**: Aligning across different `it` blocks or test methods
+- **Consistency**: Maintain consistent alignment patterns within each test scope
+
+### Test Coverage Requirements
+- All public methods must have corresponding test cases
+- Edge cases and error conditions must be tested
+- Fixture files should cover various scenarios (minimal, complete, invalid, edge cases)
+- Test descriptions should be clear and specific
+
+## Documentation
+- Maintain comprehensive README with examples
+- Document all public methods with YARD comments
+- Include schema field descriptions in code comments
+- Support multiple schema versions (1.0, 2.0, 2.1-draft)
+
+## Implementation Status
+- ✅ Core reading functionality complete
+- ✅ All schema fields implemented and tested
+- ✅ Comprehensive test suite (156 test cases)
+- ✅ Error handling with custom exception classes
+- ✅ Multi-value field support (singular/plural methods)
+- ✅ Page objects with full attribute support
+- ✅ Enum validation and type coercion
+- ✅ Unicode and special character handling
+
+## Future Considerations
+- XML writing/generation capabilities (.to_xml method)
+- JSON export (.to_json method) - **Partially implemented**
+- YAML export (.to_yaml method) - **Partially implemented**
+- Schema version detection and migration
+- CLI tool for ComicInfo manipulation

data/lib/comicinfo/enums.rb

@@ -0,0 +1,169 @@
+module ComicInfo
+  module Enums
+    # YesNo enum values for BlackAndWhite field
+    YES_NO_VALUES = %w[Unknown No Yes].freeze
+
+    # Manga enum values including right-to-left reading direction
+    MANGA_VALUES = %w[Unknown No Yes YesAndRightToLeft].freeze
+
+    # Age rating enum values from ComicInfo schema
+    AGE_RATING_VALUES = [
+      'Unknown',
+      'Adults Only 18+',
+      'Early Childhood',
+      'Everyone',
+      'Everyone 10+',
+      'G',
+      'Kids to Adults',
+      'M',
+      'MA15+',
+      'Mature 17+',
+      'PG',
+      'R18+',
+      'Rating Pending',
+      'Teen',
+      'X18+'
+    ].freeze
+
+    # Comic page type enum values
+    COMIC_PAGE_TYPE_VALUES = %w[
+      FrontCover
+      InnerCover
+      Roundup
+      Story
+      Advertisement
+      Editorial
+      Letters
+      Preview
+      BackCover
+      Other
+      Deleted
+    ].freeze
+
+    # Default values from XSD schema
+    DEFAULT_STRING = ''.freeze
+    DEFAULT_INTEGER = -1
+    DEFAULT_ENUM_UNKNOWN = 'Unknown'.freeze
+    DEFAULT_PAGE_COUNT = 0
+    DEFAULT_PAGE_TYPE = 'Story'.freeze
+    DEFAULT_DOUBLE_PAGE = false
+    DEFAULT_IMAGE_SIZE = 0
+
+    # Validation methods
+    module Validators
+      # Validates YesNo enum values
+      def self.validate_yes_no value
+        return DEFAULT_ENUM_UNKNOWN if value.nil? || value.empty?
+
+        raise Errors::InvalidEnumError.new('BlackAndWhite', value, YES_NO_VALUES) unless YES_NO_VALUES.include?(value)
+
+        value
+      end
+
+      # Validates Manga enum values
+      def self.validate_manga value
+        return DEFAULT_ENUM_UNKNOWN if value.nil? || value.empty?
+
+        raise Errors::InvalidEnumError.new('Manga', value, MANGA_VALUES) unless MANGA_VALUES.include?(value)
+
+        value
+      end
+
+      # Validates AgeRating enum values
+      def self.validate_age_rating value
+        return DEFAULT_ENUM_UNKNOWN if value.nil? || value.empty?
+
+        raise Errors::InvalidEnumError.new('AgeRating', value, AGE_RATING_VALUES) unless AGE_RATING_VALUES.include?(value)
+
+        value
+      end
+
+      # Validates ComicPageType enum values
+      def self.validate_comic_page_type value
+        return DEFAULT_PAGE_TYPE if value.nil? || value.empty?
+
+        # Handle space-separated list of values
+        values = value.split(/\s+/)
+        values.each do |v|
+          unless COMIC_PAGE_TYPE_VALUES.include?(v)
+            raise Errors::InvalidEnumError.new('ComicPageType', v, COMIC_PAGE_TYPE_VALUES)
+          end
+        end
+
+        value
+      end
+
+      # Validates CommunityRating decimal range (0.0 to 5.0)
+      def self.validate_community_rating value
+        return nil if value.nil? || value.empty?
+
+        begin
+          rating = Float(value)
+          raise Errors::RangeError.new('CommunityRating', rating, 0.0, 5.0) if rating < 0.0 || rating > 5.0
+
+          rating
+        rescue ArgumentError
+          raise Errors::TypeCoercionError.new('CommunityRating', value, 'Float')
+        end
+      end
+
+      # Validates integer fields with range checking
+      def self.validate_integer value, field_name = 'integer', default = DEFAULT_INTEGER
+        return default if value.nil? || value.empty?
+
+        begin
+          Integer(value)
+        rescue ArgumentError
+          raise Errors::TypeCoercionError.new(field_name, value, 'Integer')
+        end
+      end
+
+      # Validates date components (Year, Month, Day)
+      def self.validate_year value
+        return DEFAULT_INTEGER if value.nil? || value.empty?
+
+        year = validate_integer(value, 'Year')
+        raise Errors::RangeError.new('Year', year, 1000, 9999) if year != DEFAULT_INTEGER && (year < 1000 || year > 9999)
+
+        year
+      end
+
+      def self.validate_month value
+        return DEFAULT_INTEGER if value.nil? || value.empty?
+
+        month = validate_integer(value, 'Month')
+        raise Errors::RangeError.new('Month', month, 1, 12) if month != DEFAULT_INTEGER && (month < 1 || month > 12)
+
+        month
+      end
+
+      def self.validate_day value
+        return DEFAULT_INTEGER if value.nil? || value.empty?
+
+        day = validate_integer(value, 'Day')
+        raise Errors::RangeError.new('Day', day, 1, 31) if day != DEFAULT_INTEGER && (day < 1 || day > 31)
+
+        day
+      end
+    end
+
+    # Helper methods for enum checks
+    module Helpers
+      def self.manga_right_to_left? value
+        value == 'YesAndRightToLeft'
+      end
+
+      def self.yes_value? value
+        %w[Yes YesAndRightToLeft].include?(value)
+      end
+
+      def self.no_value? value
+        value == 'No'
+      end
+
+      def self.unknown_value? value
+        value == 'Unknown' || value.nil? || value.empty?
+      end
+    end
+  end
+end

data/lib/comicinfo/errors.rb

@@ -0,0 +1,64 @@
+module ComicInfo
+  module Errors
+    # Base error class for all ComicInfo-related errors
+    class ComicInfoError < StandardError; end
+
+    # Error raised when XML parsing fails
+    class ParseError < ComicInfoError
+      def initialize message = 'Failed to parse XML'
+        super
+      end
+    end
+
+    # Error raised when file cannot be read
+    class FileError < ComicInfoError
+      def initialize message = 'Failed to read file'
+        super
+      end
+    end
+
+    # Error raised when enum values are invalid
+    class InvalidEnumError < ComicInfoError
+      attr_reader :field, :value, :valid_values
+
+      def initialize field, value, valid_values
+        @field = field
+        @value = value
+        @valid_values = valid_values
+        super("Invalid value '#{value}' for field '#{field}'. Valid values are: #{valid_values.join(', ')}")
+      end
+    end
+
+    # Error raised when numeric values are out of range
+    class RangeError < ComicInfoError
+      attr_reader :field, :value, :min, :max
+
+      def initialize field, value, min, max
+        @field = field
+        @value = value
+        @min = min
+        @max = max
+        super("Value '#{value}' for field '#{field}' is out of range (#{min}..#{max})")
+      end
+    end
+
+    # Error raised when type coercion fails
+    class TypeCoercionError < ComicInfoError
+      attr_reader :field, :value, :expected_type
+
+      def initialize field, value, expected_type
+        @field = field
+        @value = value
+        @expected_type = expected_type
+        super("Cannot convert value '#{value}' for field '#{field}' to #{expected_type}")
+      end
+    end
+
+    # Error raised when schema validation fails
+    class SchemaError < ComicInfoError
+      def initialize message = 'Schema validation failed'
+        super
+      end
+    end
+  end
+end