epub_tools 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67e06b8c37f922205445fb328c172184eb14436d876514e306892e17faf767e2
-  data.tar.gz: b0eb25344c96cca09889bc7854b40f48dca2bc49449583a1259dd7ac30803309
+  metadata.gz: 830a3d6d88e106980c19f5c19ea5e0365e39499cc90c0c32ff5c204b7cf24abd
+  data.tar.gz: 7898e152850e5e390842e04a56947e2e88623bd1e5b65525561423da7a5ec744
 SHA512:
-  metadata.gz: b36393dbb0fcc6888a10a2bdb93d30fe88eb423034aacc7455bdb8338e4a0fccdfc8fac70b9998ccd66c1758956afcef0bd8ecd404aabe5eacfa4326b5f3b847
-  data.tar.gz: f9b2071dc6a832b178fa77c8982f43f645a9ebed4059cd023863cde8ed6220300df1155cfea39ee35455188b2fcd6672abf56f3682a5f46c606891e4e1bb0347
+  metadata.gz: 7b852a22e630ad9177c5adc692326dac517b904c687e6cbe3874b7e1f43347a53cfdd381cb5b66b7feaf6faafae75129510aac6a23f84f4b3e82734ae84dc8ac
+  data.tar.gz: 4602e5922dbdf257436445546b14501a0064861af84fea854feb0a10ed2ef651d6eefb8009ce459c7463c50c3383eabe3220a10d856271ad38c49cc768b8da5f

data/.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [ main ]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest

data/.gitignore

@@ -8,4 +8,4 @@ vendor/bundle/
 
 text_style_classes.yaml
 
-**/.claude/settings.local.json
+**/.claude/

data/.rubocop.yml

@@ -16,26 +16,19 @@ plugins:
   - rubocop-minitest
   - rubocop-rake
 
-Style/FrozenStringLiteralComment:
-  Enabled: false
 
 Metrics/MethodLength:
-  Enabled: false
+  Exclude:
+    - 'test/**/*'
 
-Metrics/ClassLength:
-  Enabled: false
-
-Metrics/AbcSize:
-  Enabled: false
-
-Metrics/CyclomaticComplexity:
-  Enabled: false
+Naming/PredicateMethod:
+  Exclude:
+    - 'test/**/*'
 
-Metrics/PerceivedComplexity:
-  Enabled: false
-
-Style/OptionalBooleanParameter:
-  Enabled: false
+Metrics/ClassLength:
+  Exclude:
+    - 'test/**/*'
 
 Minitest/MultipleAssertions:
-  Enabled: false
+  Exclude:
+    - 'test/**/*'

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.5

data/CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+EPUB Tools is a Ruby gem and CLI for working with EPUB files. It provides functionality to extract, split, initialize, add chapters, pack, and unpack EPUB books. The project uses a modular architecture with separate classes for each operation and a structured CLI system.
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run a specific test file
+ruby -Itest test/specific_test.rb
+```
+
+### Linting
+```bash
+# Run RuboCop linting
+bundle exec rubocop
+
+# Fix auto-correctable issues
+bundle exec rubocop --auto-correct
+```
+
+### Dependencies
+```bash
+# Install dependencies
+bundle install
+
+# Install with documentation dependencies
+bundle install --with doc
+```
+
+### Documentation
+```bash
+# Generate and serve YARD documentation
+bundle exec yard server --reload
+# Then visit http://localhost:8808
+
+# Generate documentation files
+bundle exec yard doc
+```
+
+### Gem Management
+```bash
+# Build the gem
+gem build epub_tools.gemspec
+
+# Install locally built gem
+gem install ./epub_tools-*.gem
+```
+
+## Architecture
+
+### Core Components
+
+- **Main Module** (`lib/epub_tools.rb`): Entry point that requires all components
+- **CLI System** (`lib/epub_tools/cli/`): Object-oriented command-line interface
+  - `Runner`: Main CLI runner that handles command dispatch
+  - `CommandRegistry`: Manages available commands and their configurations
+  - `OptionBuilder`: Builds command-line option parsers
+  - `CommandOptionsConfigurator`: Handles command-specific option configuration
+- **Core Classes**: Individual operation classes for EPUB manipulation
+  - `XHTMLExtractor`: Extracts XHTML files from EPUB archives
+  - `SplitChapters`: Splits XHTML files into separate chapters
+  - `EpubInitializer`: Creates new EPUB directory structure (uses configuration pattern)
+  - `AddChapters`: Adds chapter files to existing EPUB
+  - `PackEbook`: Packages EPUB directories into .epub files
+  - `UnpackEbook`: Unpacks .epub files into directories
+  - `CompileBook`: Full workflow combining multiple operations (uses workspace pattern)
+- **Supporting Classes**: SOLID-designed helper classes
+  - `CompileWorkspace`: Manages build directories for CompileBook
+  - `ChapterValidator`: Validates chapter sequence completeness
+  - `EpubConfiguration`: Configuration object for EPUB initialization
+  - `XhtmlGenerator`: Generates XHTML templates for EPUB content
+  - `EpubMetadataBuilder`: Builds OPF metadata content
+  - `EpubFileWriter`: Handles EPUB file writing operations
+
+### CLI Architecture
+
+The CLI uses a registry-based system where:
+1. Commands are registered in `cli.rb` with their class, required parameters, and defaults
+2. The `Runner` dispatches to the appropriate command class
+3. The `CommandOptionsConfigurator` handles command-specific option setup
+4. Each command class implements a `run` method and uses the `Loggable` mixin for verbose output
+
+### Dependencies
+
+- **nokogiri**: XML/HTML parsing for EPUB content
+- **rubyzip**: ZIP file manipulation for EPUB packaging
+- **rake**: Build tasks and testing
+- **minitest**: Testing framework
+- **rubocop**: Code linting with custom configuration
+- **simplecov**: Test coverage reporting
+
+### File Structure
+
+- `bin/epub-tools`: Executable CLI entry point
+- `lib/epub_tools/`: Main library code
+- `test/`: Minitest-based test suite
+- `.rubocop.yml`: RuboCop configuration with relaxed complexity rules
+- `epub_tools.gemspec`: Gem specification
+- `Gemfile`: Dependency management
+
+### Testing Patterns
+
+Tests use Minitest with:
+- `test_helper.rb` sets up SimpleCov coverage
+- Tests in `test/` directory follow `*_test.rb` naming
+- CLI tests verify command registration and option parsing
+- Individual component tests verify core functionality
+
+### Code Quality
+
+The codebase follows SOLID principles with:
+- **Single Responsibility**: Classes have focused, well-defined purposes
+- **Open/Closed**: Extensible design through composition and dependency injection
+- **Dependency Inversion**: Configuration objects and factory patterns
+
+RuboCop configuration excludes test files from metrics cops while maintaining strict standards for production code.

data/Gemfile

@@ -6,18 +6,18 @@ source 'https://rubygems.org'
 
 gem 'nokogiri', '~> 1.18'
 gem 'rake', '~> 13.2'
-gem 'rubyzip', '~> 2.4'
+gem 'rubyzip', '~> 3.2'
 
 group :test, :development do
-  gem 'minitest', '~> 5.25'
+  gem 'minitest', '~> 6.0'
   gem 'rubocop', '~> 1.75', require: false
-  gem 'rubocop-minitest', '~> 0.38.0', require: false
+  gem 'rubocop-minitest', '~> 0.39.0', require: false
   gem 'rubocop-rake', '~> 0.7.1', require: false
   gem 'simplecov', require: false
 end
 
 group :doc do
-  gem 'rdoc', '~> 6.13'
+  gem 'rdoc', '~> 7.2'
   gem 'webrick', '~> 1.9'
   gem 'yard', '~> 0.9.37'
 end

data/Gemfile.lock

@@ -2,43 +2,49 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    date (3.4.1)
+    date (3.5.1)
     docile (1.4.1)
-    json (2.11.3)
-    language_server-protocol (3.17.0.4)
+    drb (2.2.3)
+    erb (6.0.2)
+    json (2.18.1)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    minitest (5.25.5)
-    nokogiri (1.18.8-aarch64-linux-gnu)
+    minitest (6.0.2)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    nokogiri (1.19.1-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.8-aarch64-linux-musl)
+    nokogiri (1.19.1-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.8-arm-linux-gnu)
+    nokogiri (1.19.1-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.8-arm-linux-musl)
+    nokogiri (1.19.1-arm-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.8-arm64-darwin)
+    nokogiri (1.19.1-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-darwin)
+    nokogiri (1.19.1-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-gnu)
+    nokogiri (1.19.1-x86_64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-musl)
+    nokogiri (1.19.1-x86_64-linux-musl)
       racc (~> 1.4)
     parallel (1.27.0)
-    parser (3.3.8.0)
+    parser (3.3.10.2)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
-    psych (5.2.3)
+    prism (1.9.0)
+    psych (5.3.1)
       date
       stringio
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    rdoc (6.13.1)
+    rake (13.3.1)
+    rdoc (7.2.0)
+      erb
       psych (>= 4.0.0)
-    regexp_parser (2.10.0)
-    rubocop (1.75.4)
+      tsort
+    regexp_parser (2.11.3)
+    rubocop (1.84.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -46,13 +52,13 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-minitest (0.38.0)
+      prism (~> 1.7)
+    rubocop-minitest (0.39.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
@@ -60,19 +66,20 @@ GEM
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
     ruby-progressbar (1.13.0)
-    rubyzip (2.4.1)
+    rubyzip (3.2.2)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.1)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    stringio (3.1.7)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
-    webrick (1.9.1)
-    yard (0.9.37)
+    stringio (3.2.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webrick (1.9.2)
+    yard (0.9.38)
 
 PLATFORMS
   aarch64-linux-gnu
@@ -85,20 +92,20 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
-  minitest (~> 5.25)
+  minitest (~> 6.0)
   nokogiri (~> 1.18)
   rake (~> 13.2)
-  rdoc (~> 6.13)
+  rdoc (~> 7.2)
   rubocop (~> 1.75)
-  rubocop-minitest (~> 0.38.0)
+  rubocop-minitest (~> 0.39.0)
   rubocop-rake (~> 0.7.1)
-  rubyzip (~> 2.4)
+  rubyzip (~> 3.2)
   simplecov
   webrick (~> 1.9)
   yard (~> 0.9.37)
 
 RUBY VERSION
-   ruby 3.4.3p32
+   ruby 3.4.5p51
 
 BUNDLED WITH
-   2.6.7
+   2.7.0

data/README.md

@@ -1,16 +1,20 @@
  # EPUB Tools
 
-[![Build Status](https://github.com/jaimerodas/epub_tools/actions/workflows/ci.yml/badge.svg)](https://github.com/jaimerodas/epub_tools/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Build Status](https://github.com/jaimerodas/epub_tools/actions/workflows/ci.yml/badge.svg)](https://github.com/jaimerodas/epub_tools/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Gem Version](https://badge.fury.io/rb/epub_tools.svg)](https://badge.fury.io/rb/epub_tools)
 
 **TL;DR:** A Ruby gem and CLI for working with EPUB files: extract, split, initialize, add chapters, pack, and unpack EPUB books.
 
 ## Installation
-Install the gem via RubyGems:
+
+### Requirements
+- Ruby 3.2 or higher
+
+### Install from RubyGems
 ```bash
 gem install epub_tools
 ```
 
-Or build and install locally:
+### Build and install locally
 ```bash
 bundle install
 gem build epub_tools.gemspec
@@ -101,7 +105,7 @@ EpubTools::UnpackEbook.new('MyBook.epub', 'unpacked_dir').run
 ## Development & Testing
 Clone the repo and install dependencies:
 ```bash
-git clone <repo-url>
+git clone https://github.com/jaimerodas/epub_tools.git
 cd epub_tools
 bundle install
 ```
@@ -111,9 +115,9 @@ Run tests:
 bundle exec rake test
 ```
 
-Enable coverage reporting:
+Run linting (RuboCop):
 ```bash
-COVERAGE=true bundle exec rake test
+bundle exec rubocop
 ```
 ## Documentation
 

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rake/testtask'
 
 desc 'Run all tests'

data/bin/epub-tools

@@ -1,4 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
 require_relative '../lib/epub_tools'
 
 # Use the new object-oriented CLI architecture

data/epub_tools.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'lib/epub_tools/version'
 
 Gem::Specification.new do |spec|
@@ -20,5 +22,5 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'nokogiri', '~> 1.18'
   spec.add_dependency 'rake', '~> 13.2'
-  spec.add_dependency 'rubyzip', '~> 2.4'
+  spec.add_dependency 'rubyzip', '~> 3.2'
 end

data/lib/epub_tools/add_chapters.rb

@@ -1,4 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
 require 'nokogiri'
 require 'fileutils'
 require_relative 'loggable'
@@ -7,6 +9,7 @@ module EpubTools
   # Moves new chapters into an unpacked EPUB
   class AddChapters
     include Loggable
+
     # Initializes the class
     # @param options [Hash] Configuration options
     # @option options [String] :chapters_dir Directory from which to move the xhtml chapters.
@@ -18,7 +21,7 @@ module EpubTools
     # @option options [Boolean] :verbose Whether to log progress to STDOUT (default: false)
     def initialize(options = {})
       @chapters_dir = File.expand_path(options[:chapters_dir] || './chapters')
-      @epub_dir = File.expand_path(options[:epub_dir] || './epub/OEBPS')
+      @epub_dir = File.expand_path(options[:oebps_dir] || './epub/OEBPS')
       @opf_file = File.join(@epub_dir, 'package.opf')
       @nav_file = File.join(@epub_dir, 'nav.xhtml')
       @verbose = options[:verbose] || false
@@ -80,24 +83,7 @@ module EpubTools
       manifest = doc.at_xpath('//xmlns:manifest')
       spine = doc.at_xpath('//xmlns:spine')
 
-      filenames.each do |filename|
-        id = chapter_id(filename)
-        # Add <item> to the manifest if missing
-        unless doc.at_xpath("//xmlns:item[@href='#{filename}']")
-          item = Nokogiri::XML::Node.new('item', doc)
-          item['id'] = id
-          item['href'] = filename
-          item['media-type'] = 'application/xhtml+xml'
-          manifest.add_child(item)
-        end
-
-        # Add <itemref> to the spine if missing
-        next if doc.at_xpath("//xmlns:itemref[@idref='#{id}']")
-
-        itemref = Nokogiri::XML::Node.new('itemref', doc)
-        itemref['idref'] = id
-        spine.add_child(itemref)
-      end
+      filenames.each { |filename| update_opf_for_file(doc, manifest, spine, filename) }
 
       File.write(@opf_file, doc.to_xml(indent: 2))
     end
@@ -106,19 +92,51 @@ module EpubTools
       doc = Nokogiri::XML(File.read(@nav_file)) { |config| config.default_xml.noblanks }
       nav = doc.at_xpath('//xmlns:nav[@epub:type="toc"]/xmlns:ol')
 
-      filenames.each do |filename|
-        # Create a new <li><a href="...">Label</a></li> element
-        label = File.basename(filename, '.xhtml').gsub('_', ' ').capitalize
-        label = 'Prologue' if label == 'Chapter 0'
-        li = Nokogiri::XML::Node.new('li', doc)
-        a  = Nokogiri::XML::Node.new('a', doc)
-        a['href'] = filename
-        a.content = label
-        li.add_child(a)
-        nav.add_child(li)
-      end
+      filenames.each { |filename| nav.add_child(create_nav_link(doc, filename)) }
 
       File.write(@nav_file, doc.to_xml(indent: 2))
     end
+
+    def create_nav_link(doc, filename)
+      li = Nokogiri::XML::Node.new('li', doc)
+      a = Nokogiri::XML::Node.new('a', doc)
+      a['href'] = filename
+      a.content = format_chapter_label(filename)
+      li.add_child(a)
+      li
+    end
+
+    def format_chapter_label(filename)
+      label = File.basename(filename, '.xhtml').gsub('_', ' ').capitalize
+      label == 'Chapter 0' ? 'Prologue' : label
+    end
+
+    def update_opf_for_file(doc, manifest, spine, filename)
+      id = chapter_id(filename)
+      add_manifest_item(doc, manifest, filename, id) unless manifest_item_exists?(doc, filename)
+      add_spine_itemref(doc, spine, id) unless spine_itemref_exists?(doc, id)
+    end
+
+    def manifest_item_exists?(doc, filename)
+      doc.at_xpath("//xmlns:item[@href='#{filename}']")
+    end
+
+    def spine_itemref_exists?(doc, id)
+      doc.at_xpath("//xmlns:itemref[@idref='#{id}']")
+    end
+
+    def add_manifest_item(doc, manifest, filename, id)
+      item = Nokogiri::XML::Node.new('item', doc)
+      item['id'] = id
+      item['href'] = filename
+      item['media-type'] = 'application/xhtml+xml'
+      manifest.add_child(item)
+    end
+
+    def add_spine_itemref(doc, spine, id)
+      itemref = Nokogiri::XML::Node.new('itemref', doc)
+      itemref['idref'] = id
+      spine.add_child(itemref)
+    end
   end
 end

data/lib/epub_tools/chapter_validator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'loggable'
+
+module EpubTools
+  # Validates chapter sequence completeness
+  class ChapterValidator
+    include Loggable
+
+    def initialize(chapters_dir:, verbose: false)
+      @chapters_dir = chapters_dir
+      @verbose = verbose
+    end
+
+    def validate
+      log 'Validating chapter sequence...'
+      nums = extract_chapter_numbers
+      check_sequence_completeness(nums)
+      log "Chapter sequence is complete: #{nums.first} to #{nums.last}."
+    end
+
+    private
+
+    def extract_chapter_numbers
+      nums = Dir.glob(File.join(@chapters_dir, '*.xhtml')).map do |file|
+        if (m = File.basename(file, '.xhtml').match(/_(\d+)\z/))
+          m[1].to_i
+        end
+      end.compact
+      raise "No chapter files found in #{@chapters_dir}" if nums.empty?
+
+      nums.sort.uniq
+    end
+
+    def check_sequence_completeness(sorted)
+      missing = (sorted.first..sorted.last).to_a - sorted
+      raise "Missing chapter numbers: #{missing.join(' ')}" if missing.any?
+    end
+  end
+end