shoko 0.1.0

data/lib/shoko/adapters/book_sources/epub/parsers/opf/navigation_extractor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'navigation_source_locator'
+require_relative 'navigation_selector'
+require_relative 'navigation_traversal'
+require_relative 'navigation_result'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Coordinates extraction of navigation entries from nav/NCX sources.
+    class OPFNavigationExtractor
+      def initialize(opf:, entry_reader:)
+        @source_locator = OPFNavigationSourceLocator.new(opf: opf, entry_reader: entry_reader)
+        @traversal = OPFNavigationTraversal.new(entry_reader: entry_reader)
+        @selector = OPFNavigationSelector.new(opf: opf)
+        @result_class = OPFNavigationResult
+      end
+
+      def extract(manifest)
+        nav_bundle = extract_from_nav
+        ncx_bundle = extract_from_ncx(manifest)
+        @selector.choose(nav_bundle, ncx_bundle, manifest)
+      end
+
+      private
+
+      def extract_from_nav
+        nav_path = @source_locator.nav_path
+        return empty_result unless nav_path
+
+        @traversal.from_nav_path(nav_path)
+      end
+
+      def extract_from_ncx(manifest)
+        ncx_path = @source_locator.ncx_path(manifest)
+        return empty_result unless ncx_path
+
+        @traversal.from_ncx_path(ncx_path)
+      end
+
+      def empty_result
+        @result_class.new(toc_entries: [], titles: {})
+      end
+    end
+  end
+end

data/lib/shoko/adapters/book_sources/epub/parsers/opf/navigation_label_resolver.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+require_relative '../html_processor'
+require_relative 'navigation_document_index'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Resolves placeholder navigation labels using heading fallbacks.
+    class OPFNavigationLabelResolver
+      PLACEHOLDER_PATTERN = /\A[cC][0-9A-Za-z]{2,}\z/
+
+      attr_reader :source_path
+
+      def initialize(entry_reader:, source_path:)
+        @entry_reader = entry_reader
+        @source_path = source_path
+        @text_cleaner = HTMLProcessor
+        @document_index = OPFNavigationDocumentIndex.new(entry_reader: entry_reader, cleaner: self)
+      end
+
+      def clean_label(text)
+        @text_cleaner.clean_html(text.to_s).strip
+      end
+
+      def resolve(href:, title:)
+        stripped = title.to_s.strip
+        return stripped unless href && (stripped.empty? || stripped.match?(PLACEHOLDER_PATTERN))
+
+        clean_label(fallback_label_for(href, stripped))
+      rescue StandardError
+        stripped
+      end
+
+      def document_and_anchor(href:)
+        decoded = CGI.unescape(href.to_s)
+        return [nil, nil] if decoded.empty?
+
+        base, anchor = decoded.split('#', 2)
+        return [nil, anchor] if base.to_s.empty? || @source_path.to_s.empty?
+
+        [expanded_document_path(base), anchor]
+      end
+
+      def target_for(href:)
+        document_path, = document_and_anchor(href: href)
+        return [nil, nil] unless document_path
+
+        [document_path, @entry_reader.opf_relative_path(document_path)]
+      end
+
+      private
+
+      def fallback_label_for(href, stripped)
+        candidate = heading_label_for(href)
+        candidate.to_s.strip.empty? ? stripped : candidate
+      end
+
+      def expanded_document_path(base)
+        base_dir = File.dirname(@source_path)
+        @entry_reader.expand_path(base_dir, base)
+      end
+
+      def heading_label_for(href)
+        document_path, anchor = document_and_anchor(href: href)
+        return nil unless document_path
+
+        return anchor_label(document_path, anchor) if anchor
+
+        @document_index.next_heading(document_path)
+      end
+
+      def anchor_label(document_path, anchor)
+        candidate = @document_index.anchor_label(document_path, anchor)
+        @document_index.remove_heading(document_path, candidate) if candidate
+        return candidate unless candidate.to_s.strip.empty?
+
+        @document_index.next_heading(document_path)
+      end
+    end
+  end
+end

data/lib/shoko/adapters/book_sources/epub/parsers/opf/navigation_list_item.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Extracts href and cleaned label text from a nav list item.
+    class OPFNavigationListItem
+      def initialize(list_item, cleaner:)
+        @list_item = list_item
+        @cleaner = cleaner
+        @empty_text = ''
+      end
+
+      def href
+        anchor&.attributes&.[]('href')
+      end
+
+      def title
+        return clean_text(anchor.texts.join) if anchor
+
+        clean_text(list_item_text)
+      end
+
+      private
+
+      def clean_text(text)
+        @cleaner.clean_label(text)
+      end
+
+      def anchor
+        @anchor ||= begin
+          elements = @list_item.elements
+          elements['./*[local-name()="a"]'] || elements['.//*[local-name()="a"]']
+        end
+      end
+
+      def list_item_text
+        stop_element = list_container_element
+        @list_item.children.take_while { |child| child != stop_element }.each_with_object(+'') do |child, buffer|
+          buffer << node_text(child)
+        end
+      end
+
+      def list_container_element
+        @list_item.elements['./*[local-name()="ol" or local-name()="ul"]']
+      end
+
+      def node_text(child)
+        text = child.to_s
+        text.empty? ? @empty_text : text
+      end
+    end
+  end
+end

data/lib/shoko/adapters/book_sources/epub/parsers/opf/navigation_result.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Value object for extracted TOC entries and title map.
+    OPFNavigationResult = Struct.new(:toc_entries, :titles, keyword_init: true)
+  end
+end

data/lib/shoko/adapters/book_sources/epub/parsers/opf/navigation_selector.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'navigation_result'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Chooses the best navigation source based on spine coverage.
+    class OPFNavigationSelector
+      # Value object for paired nav/NCX entries.
+      EntryPair = Struct.new(:nav_entries, :ncx_entries, keyword_init: true)
+      private_constant :EntryPair
+
+      # Value object for availability of entries in each source.
+      EntryAvailability = Struct.new(:nav_entries, :ncx_entries, keyword_init: true) do
+        def selection
+          nav_empty = nav_entries.empty?
+          ncx_empty = ncx_entries.empty?
+          if nav_empty && ncx_empty
+            []
+          elsif ncx_empty
+            nav_entries
+          elsif nav_empty
+            ncx_entries
+          end
+        end
+      end
+      private_constant :EntryAvailability
+
+      # Selects entries with fallback to spine coverage comparison.
+      class EntrySelection
+        def initialize(pair, spine_index)
+          @pair = pair
+          @availability = EntryAvailability.new(
+            nav_entries: pair.nav_entries,
+            ncx_entries: pair.ncx_entries
+          )
+          @coverage = SpineCoverage.new(spine_index)
+        end
+
+        def entries
+          selection = @availability.selection
+          return selection if selection
+
+          @coverage.prefer(@pair.nav_entries, @pair.ncx_entries)
+        end
+      end
+
+      # Computes spine coverage to decide between nav and NCX entries.
+      class SpineCoverage
+        def initialize(spine_index)
+          @spine_index = spine_index
+        end
+
+        def prefer(nav_entries, ncx_entries)
+          nav_score = score(nav_entries)
+          ncx_score = score(ncx_entries)
+          nav_score >= ncx_score ? nav_entries : ncx_entries
+        end
+
+        private
+
+        def score(entries)
+          entries.count do |entry|
+            href = entry[:opf_href]
+            href && @spine_index[href]
+          end
+        end
+      end
+
+      def initialize(opf:)
+        @opf = opf
+        @result_class = OPFNavigationResult
+      end
+
+      def choose(nav_bundle, ncx_bundle, manifest)
+        pair = EntryPair.new(nav_entries: nav_bundle.toc_entries, ncx_entries: ncx_bundle.toc_entries)
+        entries = EntrySelection.new(pair, build_spine_index(manifest)).entries
+        return empty_result if entries.empty?
+
+        titles = ncx_bundle.titles.merge(nav_bundle.titles)
+        @result_class.new(toc_entries: entries, titles: titles)
+      end
+
+      private
+
+      def empty_result
+        @result_class.new(toc_entries: [], titles: {})
+      end
+
+      def build_spine_index(manifest)
+        hrefs = {}
+        @opf.elements.each('//spine/itemref') do |itemref|
+          href = manifest[itemref.attributes['idref']]
+          hrefs[href] = true if href
+        end
+        hrefs
+      end
+    end
+  end
+end

data/lib/shoko/adapters/book_sources/epub/parsers/opf/navigation_source_locator.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Locates nav and NCX sources referenced by an OPF manifest.
+    class OPFNavigationSourceLocator
+      NAV_PROPERTY = 'nav'
+      NCX_EXTENSION = '.ncx'
+      NCX_MEDIA_HINT = 'ncx'
+
+      def initialize(opf:, entry_reader:)
+        @opf = opf
+        @entry_reader = entry_reader
+        @decoder = CGI
+      end
+
+      def nav_path
+        @opf.elements.each('//manifest/item') do |item|
+          nav_path = nav_item_path(item)
+          return nav_path if nav_path
+        end
+
+        nil
+      end
+
+      def ncx_path(manifest)
+        spine_path = ncx_path_from_spine(manifest)
+        return spine_path if spine_path
+
+        candidate_ncx_paths.each do |candidate|
+          return candidate if candidate && @entry_reader.entry_exists?(candidate)
+        end
+
+        nil
+      end
+
+      private
+
+      def nav_item_path(item)
+        properties_attr, href_attr = item.attributes.values_at('properties', 'href')
+        properties = properties_attr&.value.to_s.split
+        return nil unless properties.include?(NAV_PROPERTY)
+
+        entry_path_for(href_attr&.value)
+      end
+
+      def ncx_path_from_spine(manifest)
+        ncx_id = @opf.elements['//spine']&.attributes&.[]('toc')
+        return nil unless ncx_id
+
+        ncx_href = manifest[ncx_id]
+        entry_path_for(ncx_href)
+      end
+
+      def candidate_ncx_paths
+        @opf.elements.each_with_object([]) do |item, paths|
+          candidate_path = ncx_candidate_path(item)
+          paths << candidate_path if candidate_path
+        end
+      end
+
+      def ncx_candidate_path(item)
+        href_attr, media_attr = item.attributes.values_at('href', 'media-type')
+        decoded = decoded_href(href_attr&.value)
+        media_type = media_attr&.value.to_s.downcase
+        return @entry_reader.join_path(decoded) if decoded &&
+                                                   (media_type.include?(NCX_MEDIA_HINT) ||
+                                                    decoded.downcase.end_with?(NCX_EXTENSION))
+
+        nil
+      end
+
+      def decoded_href(href)
+        href_string = href.to_s
+        return nil if href_string.empty?
+
+        @decoder.unescape(href_string)
+      end
+
+      def entry_path_for(href)
+        decoded = decoded_href(href)
+        return nil unless decoded
+
+        path = @entry_reader.join_path(decoded)
+        return nil unless path && @entry_reader.entry_exists?(path)
+
+        path
+      end
+    end
+  end
+end

data/lib/shoko/adapters/book_sources/epub/parsers/opf/navigation_traversal.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+
+require_relative 'navigation_context'
+require_relative 'navigation_walker'
+require_relative 'navigation_result'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Parses nav/NCX documents and builds navigation entries with fallback labels.
+    class OPFNavigationTraversal
+      NAV_TYPE_ATTRIBUTES = %w[epub:type type role].freeze
+      NAV_TOC_TYPES = %w[toc doc-toc].freeze
+
+      def initialize(entry_reader:)
+        @entry_reader = entry_reader
+        @result_class = OPFNavigationResult
+        @type_attributes = NAV_TYPE_ATTRIBUTES
+        @toc_types = NAV_TOC_TYPES
+      end
+
+      def from_nav_path(path)
+        list = nav_list_from_path(path)
+        return empty_result unless list
+
+        context = build_context(path)
+        OPFNavigationWalker.new(context).walk_nav_list(list)
+        context.to_result(@result_class)
+      end
+
+      def from_ncx_path(path)
+        nav_map = nav_map_from_path(path)
+        return empty_result unless nav_map
+
+        context = build_context(path)
+        OPFNavigationWalker.new(context).walk_nav_points(nav_map)
+        context.to_result(@result_class)
+      end
+
+      private
+
+      def empty_result
+        @result_class.new(toc_entries: [], titles: {})
+      end
+
+      def build_context(source_path)
+        OPFNavigationContext.root(source_path: source_path, entry_reader: @entry_reader)
+      end
+
+      def find_nav_toc_node(doc)
+        doc.elements.each('//*[local-name()="nav"]') do |nav|
+          return nav if nav_toc_type?(nav_type_value(nav))
+        end
+
+        nil
+      end
+
+      def nav_toc_type?(value)
+        return false unless value
+
+        @toc_types.include?(value.to_s.strip.downcase)
+      end
+
+      def nav_type_value(nav)
+        attributes = nav.attributes
+        attribute = attributes.enum_for(:each_attribute).find do |attr|
+          type_attribute?(attr.expanded_name) || type_attribute?(attr.name)
+        end
+        attribute&.value
+      end
+
+      def type_attribute?(name)
+        @type_attributes.include?(name)
+      end
+
+      def nav_list_from_path(path)
+        content = @entry_reader.safe_read_entry(path)
+        return nil unless content
+
+        doc = REXML::Document.new(content)
+        nav_list_from_document(doc)
+      rescue REXML::ParseException
+        nil
+      end
+
+      def nav_list_from_document(doc)
+        nav = find_nav_toc_node(doc)
+        return nil unless nav
+
+        nav.elements['(.//*[local-name()="ol"] | .//*[local-name()="ul"])[1]']
+      end
+
+      def nav_map_from_path(path)
+        ncx_content = @entry_reader.read_entry(path)
+        ncx = REXML::Document.new(ncx_content)
+        ncx.elements['//navMap']
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/shoko/adapters/book_sources/epub/parsers/opf/navigation_walker.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Walks nav/NCX trees to populate navigation context entries.
+    class OPFNavigationWalker
+      def initialize(context)
+        @context = context
+        @list_item_tag = 'li'
+        @list_container_tags = %w[ol ul]
+      end
+
+      def walk_nav_points(node)
+        node.each_element('navPoint') do |nav_point|
+          title, href = @context.entry_for_nav_point(nav_point)
+          @context.add_entry(title: title, href: href)
+          self.class.new(@context.next_level).walk_nav_points(nav_point)
+        end
+      end
+
+      def walk_nav_list(list)
+        list.each_element do |child|
+          next unless child.is_a?(REXML::Element) && child.name.casecmp(@list_item_tag).zero?
+
+          process_list_item(child)
+        end
+      end
+
+      private
+
+      def process_list_item(child)
+        title, href = @context.entry_for_list_item(child)
+        @context.add_entry(title: title, href: href)
+        walk_nested_list(child)
+      end
+
+      def walk_nested_list(child)
+        nested = nested_list(child)
+        return unless nested
+
+        self.class.new(@context.next_level).walk_nav_list(nested)
+      end
+
+      def nested_list(child)
+        elements = child.elements
+        @list_container_tags.each do |tag|
+          list = elements["./*[local-name()=\"#{tag}\"]"]
+          return list if list
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/shoko/adapters/book_sources/epub/parsers/opf_processor.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'rexml/document'
+
+require_relative '../../../monitoring/perf_tracer.rb'
+require_relative 'opf/entry_reader'
+require_relative 'opf/metadata_extractor'
+require_relative 'opf/navigation_extractor'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Processes OPF files.
+    class OPFProcessor
+      # Value object describing a resolved spine item.
+      SpineItem = Struct.new(:file_path, :number, :title, :href, keyword_init: true)
+      private_constant :SpineItem
+
+      attr_reader :toc_entries
+
+      def initialize(opf_path, zip: nil)
+        @opf_path = opf_path
+        @entry_reader = OPFEntryReader.new(opf_path, zip: zip)
+        content = read_opf_content
+        @opf = Shoko::Adapters::Monitoring::PerfTracer.measure('opf.parse') do
+          REXML::Document.new(content)
+        end
+        @toc_entries = []
+        @navigation_extractor = OPFNavigationExtractor.new(opf: @opf, entry_reader: @entry_reader)
+      end
+
+      def extract_metadata
+        OPFMetadataExtractor.new(@opf).extract
+      end
+
+      def build_manifest_map
+        manifest = {}
+        @opf.elements.each('//manifest/item') do |item|
+          id, href = manifest_item_id_href(item)
+          next unless id && href
+
+          normalized = @entry_reader.normalize_opf_relative_href(CGI.unescape(href))
+          manifest[id] = normalized if normalized
+        end
+        manifest
+      end
+
+      def extract_chapter_titles(manifest)
+        result = @navigation_extractor.extract(manifest)
+        @toc_entries = result.toc_entries
+        result.titles
+      end
+
+      def process_spine(manifest, chapter_titles)
+        chapter_num = 1
+        @opf.elements.each('//spine/itemref') do |itemref|
+          item = build_spine_item(itemref, chapter_num, manifest, chapter_titles)
+          next unless item
+
+          yield(item)
+          chapter_num += 1
+        end
+      end
+
+      private
+
+      def read_opf_content
+        raw = if @entry_reader.zip?
+                Shoko::Adapters::Monitoring::PerfTracer.measure('zip.read') do
+                  @entry_reader.read_raw(@opf_path)
+                end
+              else
+                @entry_reader.read_raw(@opf_path)
+              end
+        @entry_reader.normalize_xml_text(raw)
+      end
+
+      def manifest_item_id_href(item)
+        attrs = item.attributes
+        [attrs['id'], attrs['href']]
+      end
+
+      def build_spine_item(itemref, number, manifest, chapter_titles)
+        idref = itemref.attributes['idref']
+        return nil unless idref
+
+        href = manifest[idref]
+        return nil unless href
+
+        file_path = @entry_reader.join_path(href)
+        return nil unless file_path && @entry_reader.entry_exists?(file_path)
+
+        SpineItem.new(
+          file_path: file_path,
+          number: number,
+          title: chapter_titles[href],
+          href: href
+        )
+      end
+    end
+  end
+end