epub_tools 0.5.0 → 0.9.0

data/lib/epub_tools/split_chapters.rb

@@ -1,54 +1,36 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require 'nokogiri'
-require 'yaml'
 require 'fileutils'
 require_relative 'loggable'
 require_relative 'style_finder'
 require_relative 'xhtml_cleaner'
 
 module EpubTools
-  # Takes a Google Docs generated, already extracted from their EPUB, XHTML files with multiple
-  # chapters and it:
-  # - Extracts classes using {StyleFinder}[rdoc-ref:EpubTools::StyleFinder]
-  # - Looks for tags that say something like Chapter XX or Prologue and splits the text there
-  # - Creates new chapter_XX.xhtml files that are cleaned using
-  #   {XHTMLCleaner}[rdoc-ref:EpubTools::XHTMLCleaner]
-  # - Saves those files to +output_dir+
+  # Splits a multi-chapter XHTML file into individual chapter files, named +chapter_N.xhtml+. A chapter starts at
+  # a "Chapter N" marker; "Chapter N (continued)" starts chapter N.5 and "Prologue" starts chapter 0.
   class SplitChapters
     include Loggable
 
-    # Initializes the class
-    # @param options [Hash] Configuration options
-    # @option options [String] :input_file Path to the source XHTML (required)
-    # @option options [String] :book_title Title to use in HTML <title> tags (required)
-    # @option options [String] :output_dir Where to write chapter files (default: './chapters')
-    # @option options [String] :output_prefix Filename prefix for chapter files (default: 'chapter')
-    # @option options [Boolean] :verbose Whether to print progress to STDOUT (default: false)
+    # Tags that can contain chapter markers
+    MARKER_TAGS = %w[p span h2 h3 h4].freeze
+    # Tags that can contain prologue markers
+    PROLOGUE_TAGS = %w[h3 h4].freeze
+
     def initialize(options = {})
       @input_file    = options.fetch(:input_file)
       @book_title    = options.fetch(:book_title)
       @output_dir    = options[:output_dir] || './chapters'
-      @output_prefix = options[:output_prefix] || 'chapter'
       @verbose       = options[:verbose] || false
     end
 
     # Runs the splitter
     # @return [Array<String>] List of generated chapter file paths
     def run
-      # Prepare output dir
       FileUtils.mkdir_p(@output_dir)
-
-      # Read the doc
-      raw_content = read_and_strip_problematic_tags
-      doc = Nokogiri::HTML(raw_content)
-
-      # Find Style Classes
-      StyleFinder.new({ file_path: @input_file, verbose: @verbose }).run
-
-      chapters = extract_chapters(doc)
-      write_chapter_files(chapters)
+      doc = Nokogiri::HTML(read_and_strip_problematic_tags)
+      classes = StyleFinder.new({ file_path: @input_file, verbose: @verbose }).run
+      extract_chapters(doc).map { |number, content| write_chapter_file(number, content, classes) }
     end
 
     private
@@ -66,54 +48,39 @@ module EpubTools
         current_number, current_fragment = process_node(node, chapters, current_number, current_fragment)
       end
 
-      finalize_chapters(chapters, current_number, current_fragment)
+      chapters[current_number] = current_fragment.to_html if current_number
+      chapters
     end
 
     def process_node(node, chapters, current_number, current_fragment)
-      if chapter_marker?(node)
-        start_new_chapter(chapters, node, current_number, current_fragment)
-      elsif prologue_marker?(node)
-        start_prologue(chapters, current_number, current_fragment)
+      number = marker_number(node)
+      if number
+        start_chapter(chapters, number, current_number, current_fragment)
       else
         current_fragment&.add_child(node.dup)
         [current_number, current_fragment]
       end
     end
 
-    def chapter_marker?(node)
-      node.text.match?(/Chapter\s+\d+/i) && %w[p span h2 h3 h4].include?(node.name)
-    end
-
-    def start_new_chapter(chapters, node, current_number, current_fragment)
-      chapters[current_number] = current_fragment.to_html if current_number
-      chapter_number = node.text.match(/Chapter\s+(\d+)/i)[1].to_i
-      [chapter_number, Nokogiri::HTML::DocumentFragment.parse('')]
-    end
-
-    def start_prologue(chapters, current_number, current_fragment)
-      chapters[current_number] = current_fragment.to_html if current_number
-      [0, Nokogiri::HTML::DocumentFragment.parse('')]
+    # @return [Numeric, nil] The chapter a marker node starts, or nil when the node is not a marker
+    def marker_number(node)
+      if MARKER_TAGS.include?(node.name) && (number = node.text[/Chapter\s+(\d+)/i, 1])
+        node.text.match?(/Chapter\s+\d+\s*\(continued\)/i) ? number.to_i + 0.5 : number.to_i
+      elsif PROLOGUE_TAGS.include?(node.name) && node.text.strip.match?(/\APrologue\z/i)
+        0
+      end
     end
 
-    def finalize_chapters(chapters, current_number, current_fragment)
+    def start_chapter(chapters, number, current_number, current_fragment)
       chapters[current_number] = current_fragment.to_html if current_number
-      chapters
+      [number, Nokogiri::HTML::DocumentFragment.parse('')]
     end
 
-    def write_chapter_files(chapters)
-      chapter_files = []
-      chapters.each do |number, content|
-        filename = write_chapter_file(number, content)
-        chapter_files << filename
-      end
-      chapter_files
-    end
-
-    def write_chapter_file(label, content)
-      display_label = display_label(label)
-      filename = File.join(@output_dir, "#{@output_prefix}_#{label}.xhtml")
-      File.write(filename, build_xhtml_template(display_label, content))
-      XHTMLCleaner.new({ filename: filename }).run
+    def write_chapter_file(label, content, classes)
+      display = display_label(label)
+      filename = File.join(@output_dir, "chapter_#{file_label(label)}.xhtml")
+      File.write(filename, build_xhtml_template(display, content))
+      XHTMLCleaner.new({ filename: filename, classes: classes }).run
       log("Extracted: #{filename}")
       filename
     end
@@ -123,7 +90,7 @@ module EpubTools
         <?xml version="1.0" encoding="UTF-8"?>
         <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
           <head>
-            <title>#{@book_title} - #{display_label}</title>
+            <title>#{@book_title.encode(xml: :text)} - #{display_label}</title>
             <link rel="stylesheet" type="text/css" href="style.css"/>
           </head>
           <body>
@@ -134,16 +101,14 @@ module EpubTools
       HTML
     end
 
-    def display_label(label)
-      label.positive? ? "Chapter #{label}" : 'Prologue'
+    def file_label(label)
+      label.is_a?(Float) ? label.to_s.gsub('.', '_') : label.to_s
     end
 
-    # Detect a bolded Prologue marker
-    def prologue_marker?(node)
-      return false unless %w[h3 h4].include?(node.name)
-      return false unless node.text.strip =~ /\APrologue\z/i
+    def display_label(label)
+      return 'Prologue' if label.zero?
 
-      true
+      "Chapter #{label}"
     end
   end
 end

data/lib/epub_tools/style_finder.rb

@@ -1,69 +1,40 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require 'nokogiri'
-require 'yaml'
 require_relative 'loggable'
 
 module EpubTools
   # Finds css classes for bold and italic texts in Google Docs-generated EPUBs. Used by
-  # {XHTMLCleaner}[rdoc-ref:EpubTools::XHTMLCleaner] and
-  # {SplitChapters}[rdoc-ref:EpubTools::SplitChapters].
+  # {SplitChapters}[rdoc-ref:EpubTools::SplitChapters] to tell {XHTMLCleaner}[rdoc-ref:EpubTools::XHTMLCleaner]
+  # which spans are bold or italic.
   class StyleFinder
     include Loggable
 
     # Initializes the class
     # @param options [Hash] Configuration options
     # @option options [String] :file_path XHTML file to be analyzed (required)
-    # @option options [String] :output_path Path to write the YAML file (default: 'text_style_classes.yaml')
     # @option options [Boolean] :verbose Whether to print progress to STDOUT (default: false)
     def initialize(options = {})
       @file_path = options.fetch(:file_path)
-      @output_path = options[:output_path] || 'text_style_classes.yaml'
       @verbose = options[:verbose] || false
       raise ArgumentError, "File does not exist: #{@file_path}" unless File.exist?(@file_path)
     end
 
     # Runs the finder
-    # @return [Hash] Data containing the extracted style classes (italics and bolds)
+    # @return [Hash{Symbol => Array<String>}] The +:italics+ and +:bolds+ class names
     def run
-      style_blocks = extract_style_blocks
-      italics, bolds = extract_style_classes(style_blocks)
-      generate_output(italics, bolds)
-    end
-
-    def extract_style_blocks
-      doc = Nokogiri::HTML(File.read(@file_path))
-      doc.xpath('//style').map(&:text).join("\n")
-    end
-
-    def extract_style_classes(style_blocks)
-      italics = extract_classes(style_blocks, /font-style\s*:\s*italic/)
-      bolds = extract_classes(style_blocks, /font-weight\s*:\s*700/)
-      [italics, bolds]
-    end
-
-    def generate_output(italics, bolds)
-      print_summary(italics, bolds) if @verbose
-
-      data = { 'italics' => italics, 'bolds' => bolds }
-      File.write(@output_path, data.to_yaml)
-      data
+      styles = Nokogiri::HTML(File.read(@file_path)).xpath('//style').map(&:text).join("\n")
+      italics = classes_with(styles, /font-style\s*:\s*italic/)
+      bolds = classes_with(styles, /font-weight\s*:\s*700/)
+      log "Classes with font-style: italic: #{italics.join(', ')}" unless italics.empty?
+      log "Classes with font-weight: 700: #{bolds.join(', ')}" unless bolds.empty?
+      { italics: italics, bolds: bolds }
     end
 
     private
 
-    def extract_classes(style_text, pattern)
-      regex = /\.([\w-]+)\s*{[^}]*#{pattern.source}[^}]*}/i
-      style_text.scan(regex).flatten.uniq
-    end
-
-    def print_summary(italics, bolds)
-      log "Classes with font-style: italic: #{italics.join(', ')}" unless italics.empty?
-
-      return if bolds.empty?
-
-      log "Classes with font-weight: 700: #{bolds.join(', ')}"
+    def classes_with(styles, pattern)
+      styles.scan(/\.([\w-]+)\s*{[^}]*#{pattern.source}[^}]*}/i).flatten.uniq
     end
   end
 end

data/lib/epub_tools/unpack_ebook.rb

@@ -16,8 +16,7 @@ module EpubTools
     # @option options [Boolean] :verbose Whether to print progress to STDOUT (default: false)
     def initialize(options = {})
       @epub_file = File.expand_path(options.fetch(:epub_file))
-      output_dir = options[:output_dir]
-      @output_dir = output_dir.nil? || output_dir.empty? ? default_dir : output_dir
+      @output_dir = options[:output_dir].to_s.empty? ? default_dir : options[:output_dir]
       @verbose = options[:verbose] || false
     end
 
@@ -26,30 +25,13 @@ module EpubTools
     def run
       validate!
       FileUtils.mkdir_p(@output_dir)
-      extract_entries
+      Zip::File.extract_all(@epub_file, @output_dir) { true }
       log "Unpacked #{File.basename(@epub_file)} to #{@output_dir}"
       @output_dir
     end
 
     private
 
-    def extract_entries
-      Zip::File.open(@epub_file) do |zip|
-        zip.each do |entry|
-          extract_entry(entry)
-        end
-      end
-    end
-
-    def extract_entry(entry)
-      if entry.directory?
-        FileUtils.mkdir_p(File.join(@output_dir, entry.name))
-      else
-        FileUtils.mkdir_p(File.join(@output_dir, File.dirname(entry.name)))
-        entry.extract(destination_directory: @output_dir) { true }
-      end
-    end
-
     def default_dir
       [File.dirname(@epub_file), File.basename(@epub_file, '.epub')].join('/')
     end

data/lib/epub_tools/version.rb

@@ -2,5 +2,5 @@
 
 module EpubTools
   # Ruby Gem version number
-  VERSION = '0.5.0'
+  VERSION = '0.9.0'
 end

data/lib/epub_tools/xhtml_cleaner.rb

@@ -1,8 +1,6 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require 'nokogiri'
-require 'yaml'
 
 module EpubTools
   # Cleans Google Docs XHTMLs
@@ -12,7 +10,7 @@ module EpubTools
   #
   # - Removes any <tt><br /></tt> or <tt><hr /></tt> tags.
   # - Removes empty <tt><p></tt> tags.
-  # - Using the +class_config+, it removes <tt><span></tt> tags that are used for bold or italics and
+  # - Using the +classes+, it removes <tt><span></tt> tags that are used for bold or italics and
   #   replaces them with <tt><b></tt> or <tt><i></tt> tags.
   # - Unwraps any <tt><span></tt> tags that have no classes assigned.
   # - Outputs everything to a cleanly formatted +.xhtml+
@@ -20,12 +18,11 @@ module EpubTools
     # Initializes the class
     # @param options [Hash] Configuration options
     # @option options [String] :filename The path to the xhtml to clean (required)
-    # @option options [String] :class_config Path to a YAML file containing the bold and italic classes to check
-    #                          (default: 'text_style_classes.yaml')
+    # @option options [Hash{Symbol => Array<String>}] :classes The +:italics+ and +:bolds+ class names, as found by
+    #                          {StyleFinder}[rdoc-ref:EpubTools::StyleFinder] (required)
     def initialize(options = {})
       @filename = options.fetch(:filename)
-      class_config = options[:class_config] || 'text_style_classes.yaml'
-      @classes = YAML.load_file(class_config).transform_keys(&:to_sym)
+      @classes = options.fetch(:classes)
     end
 
     # Runs the cleaner

data/lib/epub_tools/xhtml_extractor.rb

@@ -24,12 +24,7 @@ module EpubTools
     # Runs the extraction process
     # @return [Array<String>] Paths to all extracted XHTML files
     def run
-      all_extracted_files = []
-      epub_files.each do |epub_path|
-        extracted = extract_xhtmls_from(epub_path)
-        all_extracted_files.concat(extracted) if extracted
-      end
-      all_extracted_files
+      epub_files.flat_map { |epub_path| extract_xhtmls_from(epub_path) || [] }
     end
 
     private
@@ -56,7 +51,6 @@ module EpubTools
 
       renamed = "#{epub_name}_#{File.basename(entry.name)}"
       output_path = File.join(@target_dir, renamed)
-      FileUtils.mkdir_p(File.dirname(output_path))
       entry.extract(renamed, destination_directory: @target_dir) { true }
       log output_path
       extracted_files << output_path

data/lib/epub_tools.rb

@@ -7,9 +7,13 @@ require_relative 'epub_tools/epub_initializer'
 require_relative 'epub_tools/split_chapters'
 require_relative 'epub_tools/xhtml_cleaner'
 require_relative 'epub_tools/xhtml_extractor'
+require_relative 'epub_tools/pdf_converter'
 require_relative 'epub_tools/pack_ebook'
 require_relative 'epub_tools/unpack_ebook'
+require_relative 'epub_tools/book_builder'
 require_relative 'epub_tools/compile_book'
+require_relative 'epub_tools/append_book'
+require_relative 'epub_tools/set_cover'
 require_relative 'epub_tools/cli'
 
 # Wrapper for all the other classes

data/test/add_chapters_test.rb

@@ -121,3 +121,137 @@ class AddChaptersTest < Minitest::Test
     nav_doc.xpath('//nav/ol/li/a')
   end
 end
+
+class AddChaptersHalfChapterTest < Minitest::Test
+  def setup
+    @tmp = Dir.mktmpdir
+    @chapters_dir = File.join(@tmp, 'chapters')
+    @epub_dir = File.join(@tmp, 'OEBPS')
+    Dir.mkdir(@chapters_dir)
+    Dir.mkdir(@epub_dir)
+    create_chapter_files
+    create_opf_and_nav
+  end
+
+  def teardown
+    FileUtils.remove_entry(@tmp)
+  end
+
+  def test_half_chapter_sorting_and_labels
+    result = EpubTools::AddChapters.new(chapters_dir: @chapters_dir, oebps_dir: @epub_dir).run
+
+    assert_equal %w[chapter_1.xhtml chapter_1_5.xhtml chapter_2.xhtml], result
+  end
+
+  def test_half_chapter_nav_label
+    EpubTools::AddChapters.new(chapters_dir: @chapters_dir, oebps_dir: @epub_dir).run
+
+    nav_doc = Nokogiri::XML(File.read(File.join(@epub_dir, 'nav.xhtml')))
+    nav_doc.remove_namespaces!
+    links = nav_doc.xpath('//nav/ol/li/a')
+
+    assert_equal 'Chapter 1', links[0].text
+    assert_equal 'Chapter 1.5', links[1].text
+    assert_equal 'Chapter 2', links[2].text
+  end
+
+  def test_half_chapter_opf_id
+    EpubTools::AddChapters.new(chapters_dir: @chapters_dir, oebps_dir: @epub_dir).run
+
+    doc = Nokogiri::XML(File.read(File.join(@epub_dir, 'package.opf')))
+    ids = doc.xpath('//xmlns:manifest/xmlns:item').map { |i| i['id'] }
+
+    assert_includes ids, 'chap1_5'
+  end
+
+  private
+
+  def create_chapter_files
+    File.write(File.join(@chapters_dir, 'chapter_1.xhtml'), '<html><body>Ch1</body></html>')
+    File.write(File.join(@chapters_dir, 'chapter_1_5.xhtml'), '<html><body>Ch1.5</body></html>')
+    File.write(File.join(@chapters_dir, 'chapter_2.xhtml'), '<html><body>Ch2</body></html>')
+  end
+
+  def create_opf_and_nav
+    File.write(File.join(@epub_dir, 'package.opf'), <<~XML)
+      <?xml version="1.0"?>
+      <package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="pub-id" xml:lang="en">
+        <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"></metadata>
+        <manifest></manifest>
+        <spine></spine>
+      </package>
+    XML
+    File.write(File.join(@epub_dir, 'nav.xhtml'), <<~XHTML)
+      <?xml version="1.0" encoding="utf-8"?>
+      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" lang="en">
+        <body>
+          <nav epub:type="toc" id="toc"><ol></ol></nav>
+        </body>
+      </html>
+    XHTML
+  end
+end
+
+class AddChaptersReadingOrderTest < Minitest::Test
+  def setup
+    @tmp = Dir.mktmpdir
+    @chapters_dir = File.join(@tmp, 'chapters')
+    @epub_dir = File.join(@tmp, 'OEBPS')
+    FileUtils.mkdir_p([@chapters_dir, @epub_dir])
+    create_book_with_two_chapters
+    write_chapter('chapter_1b.xhtml', '<h1>Chapter 1b: Later</h1>')
+    write_chapter('chapter_1a.xhtml', '<h1>Chapter 1a: Side</h1>')
+    write_chapter('chapter_3.xhtml', '<p>No heading</p>')
+    write_chapter('chapter_epilogue.xhtml', '<h1>Epilogue: After</h1>')
+  end
+
+  def teardown
+    FileUtils.remove_entry(@tmp)
+  end
+
+  def test_inserts_chapters_in_reading_order_with_their_headings
+    EpubTools::AddChapters.new(chapters_dir: @chapters_dir, oebps_dir: @epub_dir).run
+
+    opf = Nokogiri::XML(File.read(File.join(@epub_dir, 'package.opf')))
+    nav = Nokogiri::XML(File.read(File.join(@epub_dir, 'nav.xhtml'))).remove_namespaces!
+    spine = opf.xpath('//xmlns:itemref').map { |i| i['idref'] }
+
+    assert_equal %w[title chap1 chapter_1a chapter_1b chap2 chap3 chapter_epilogue], spine
+    assert_equal ['Title Page', 'Chapter 1', 'Chapter 1a: Side', 'Chapter 1b: Later', 'Chapter 2', 'Chapter 3',
+                  'Epilogue: After'],
+                 nav.xpath('//nav/ol/li/a').map(&:text)
+  end
+
+  private
+
+  def write_chapter(name, body)
+    File.write(File.join(@chapters_dir, name), "<html xmlns=\"http://www.w3.org/1999/xhtml\"><body>#{body}</body></html>")
+  end
+
+  def create_book_with_two_chapters
+    File.write(File.join(@epub_dir, 'package.opf'), <<~XML)
+      <?xml version="1.0"?>
+      <package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="pub-id" xml:lang="en">
+        <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"></metadata>
+        <manifest>
+          <item id="title" href="title.xhtml" media-type="application/xhtml+xml"/>
+          <item id="chap1" href="chapter_1.xhtml" media-type="application/xhtml+xml"/>
+          <item id="chap2" href="chapter_2.xhtml" media-type="application/xhtml+xml"/>
+        </manifest>
+        <spine><itemref idref="title"/><itemref idref="chap1"/><itemref idref="chap2"/></spine>
+      </package>
+    XML
+    File.write(File.join(@epub_dir, 'nav.xhtml'), <<~XHTML)
+      <?xml version="1.0" encoding="utf-8"?>
+      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" lang="en">
+        <body>
+          <nav epub:type="toc" id="toc"><ol>
+            <li><a href="title.xhtml">Title Page</a></li>
+            <li><a href="chapter_1.xhtml">Chapter 1</a></li>
+            <li><a href="chapter_2.xhtml">Chapter 2</a></li>
+          </ol></nav>
+        </body>
+      </html>
+    XHTML
+  end
+end

data/test/append_book_test.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+require_relative '../lib/epub_tools/append_book'
+
+class AppendBookTest < Minitest::Test
+  def setup
+    @tmp = Dir.mktmpdir
+    @source = File.join(@tmp, 'src')
+    @target = File.join(@tmp, 'target.epub')
+    FileUtils.mkdir_p(@source)
+    FileUtils.touch(@target)
+  end
+
+  def teardown
+    FileUtils.rm_rf(@tmp)
+  end
+
+  def test_initialize_assigns_attributes
+    ab = build_append_book(verbose: true)
+
+    assert_equal @source, ab.source_dir
+    assert_equal File.expand_path(@target), ab.target_epub
+    assert_equal @tmp, ab.build_dir
+    assert ab.verbose
+  end
+
+  def test_default_build_dir
+    ab = EpubTools::AppendBook.new(source_dir: @source, target_epub: @target)
+
+    assert ab.build_dir.end_with?('.epub_tools_build')
+  end
+
+  def test_log_outputs_when_verbose
+    ab = build_append_book(verbose: true)
+
+    assert_output("hello\n") { ab.send(:log, 'hello') }
+  end
+
+  def test_log_silent_when_not_verbose
+    ab = build_append_book(verbose: false)
+
+    assert_silent { ab.send(:log, 'hello') }
+  end
+
+  def test_detect_conflicts_raises_on_overlap
+    ab = build_append_book
+    setup_conflict_dirs(new_chapters: [1, 2], existing_chapters: [1])
+
+    error = assert_raises(ArgumentError) { ab.send(:detect_conflicts) }
+    assert_match(/chapters 1 already exist/, error.message)
+  end
+
+  def test_detect_conflicts_passes_with_no_overlap
+    ab = build_append_book
+    setup_conflict_dirs(new_chapters: [5], existing_chapters: [1, 2])
+
+    ab.send(:detect_conflicts)
+  end
+
+  def test_detect_conflicts_with_lettered_chapters
+    ab = build_append_book
+    setup_conflict_dirs(new_chapters: %w[3a 4], existing_chapters: %w[3 3a])
+
+    error = assert_raises(ArgumentError) { ab.send(:detect_conflicts) }
+    assert_match(/chapters 3a already exist/, error.message)
+  end
+
+  def test_detect_conflicts_with_half_chapters
+    ab = build_append_book
+    chapters_dir = File.join(@tmp, 'chapters')
+    oebps_dir = File.join(@tmp, 'epub', 'OEBPS')
+    FileUtils.mkdir_p([chapters_dir, oebps_dir])
+
+    FileUtils.touch(File.join(chapters_dir, 'chapter_3_5.xhtml'))
+    FileUtils.touch(File.join(oebps_dir, 'chapter_3_5.xhtml'))
+
+    error = assert_raises(ArgumentError) { ab.send(:detect_conflicts) }
+    assert_match(/3\.5 already exist/, error.message)
+  end
+
+  def test_run_completes_workflow
+    ab = build_append_book
+
+    def ab.prepare_epub; end
+    def ab.extract_xhtmls; end
+    def ab.split_xhtmls; end
+    def ab.validate_chapters; end
+    def ab.before_add_chapters; end
+    def ab.add_chapters; end
+    def ab.pack_epub; end
+
+    result = ab.run
+
+    assert_equal File.expand_path(@target), result
+  end
+
+  def test_backup_creates_bak_file
+    File.write(@target, 'epub content')
+    ab = build_append_book
+
+    ab.send(:backup_target)
+
+    backup_path = "#{File.expand_path(@target)}.bak"
+
+    assert_path_exists backup_path
+    assert_equal 'epub content', File.read(backup_path)
+  end
+
+  private
+
+  def build_append_book(verbose: false)
+    EpubTools::AppendBook.new(
+      source_dir: @source, target_epub: @target,
+      build_dir: @tmp, verbose: verbose
+    )
+  end
+
+  def setup_conflict_dirs(new_chapters:, existing_chapters:)
+    chapters_dir = File.join(@tmp, 'chapters')
+    oebps_dir = File.join(@tmp, 'epub', 'OEBPS')
+    FileUtils.mkdir_p([chapters_dir, oebps_dir])
+
+    new_chapters.each { |n| FileUtils.touch(File.join(chapters_dir, "chapter_#{n}.xhtml")) }
+    existing_chapters.each { |n| FileUtils.touch(File.join(oebps_dir, "chapter_#{n}.xhtml")) }
+  end
+end