shoko 0.1.0

data/lib/shoko/adapters/book_sources/epub/epub_resource_loader.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'zip'
+
+require_relative '../../storage/atomic_file_writer.rb'
+require_relative '../../storage/cache_paths.rb'
+require_relative '../../monitoring/logger.rb'
+
+module Shoko
+  module Adapters::BookSources::Epub
+    # Loads resources (typically images) from an EPUB on-demand and optionally
+    # persists them as per-book blobs under the cache root.
+    class EpubResourceLoader
+      SHA256_HEX_PATTERN = /\A[0-9a-f]{64}\z/i
+
+      def initialize(cache_root: CachePaths.cache_root)
+        @cache_root = cache_root
+      end
+
+      # Fetch an entry from the per-book blob cache or from the EPUB archive.
+      #
+      # @param book_sha [String,nil] 64-char hex digest identifying the book cache directory
+      # @param epub_path [String] filesystem path to the EPUB
+      # @param entry_path [String] path inside the EPUB zip
+      # @param cache_key [String,nil] logical cache key (defaults to entry_path)
+      # @return [String,nil] binary bytes
+      def fetch(book_sha:, epub_path:, entry_path:, persist: true, cache_key: nil)
+        return nil if entry_path.to_s.empty?
+
+        normalized_sha = normalize_sha(book_sha)
+        key = (cache_key || entry_path).to_s
+        return nil if key.empty?
+
+        cached = normalized_sha ? read_blob(normalized_sha, key) : nil
+        return cached if cached
+
+        bytes = read_from_zip(epub_path, entry_path)
+        return nil unless bytes
+
+        write_blob(normalized_sha, key, bytes) if persist && normalized_sha
+        bytes
+      end
+
+      def store(book_sha:, entry_path:, bytes:)
+        normalized_sha = normalize_sha(book_sha)
+        return false unless normalized_sha
+        return false if entry_path.to_s.empty?
+
+        write_blob(normalized_sha, entry_path, bytes)
+        true
+      rescue StandardError
+        false
+      end
+
+      # Resolve a resource href relative to a chapter (zip entry) path.
+      #
+      # @param chapter_entry_path [String] zip entry path of the chapter
+      # @param href [String] href/src value from XHTML
+      # @return [String,nil] normalized zip entry path
+      def self.resolve_chapter_relative(chapter_entry_path, href)
+        return nil unless chapter_entry_path && href
+
+        core = href.to_s.split(/[?#]/, 2).first.to_s
+        return nil if core.empty?
+        return nil if core.match?(/\A[a-z][a-z0-9+.-]*:/i) # data:, http:, etc.
+
+        normalized = if core.start_with?('/')
+                       core.sub(%r{\A/+}, '')
+                     else
+                       base = File.dirname(chapter_entry_path.to_s)
+                       File.expand_path(File.join('/', base, core), '/').sub(%r{^/}, '')
+                     end
+
+        normalized.empty? ? nil : normalized
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def normalize_sha(sha)
+        value = sha.to_s.strip
+        return nil if value.empty?
+        return nil unless SHA256_HEX_PATTERN.match?(value)
+
+        value.downcase
+      rescue StandardError
+        nil
+      end
+
+      def read_from_zip(epub_path, entry_path)
+        return nil unless epub_path && File.file?(epub_path)
+        return nil if entry_path.to_s.empty?
+
+        Zip::File.open(epub_path) do |zip|
+          return nil unless zip.find_entry(entry_path.to_s)
+
+          data = zip.read(entry_path.to_s)
+          data.force_encoding(Encoding::BINARY)
+          data
+        end
+      rescue Zip::Error => e
+        Shoko::Adapters::Monitoring::Logger.debug('EpubResourceLoader: zip read failed', path: epub_path.to_s, entry: entry_path.to_s,
+                                                            error: e.message)
+        nil
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('EpubResourceLoader: read failed', path: epub_path.to_s, entry: entry_path.to_s, error: e.message)
+        nil
+      end
+
+      def blob_path(book_sha, entry_path)
+        key = Digest::SHA256.hexdigest(entry_path.to_s)
+        File.join(@cache_root, 'resources', book_sha.to_s, "#{key}.bin")
+      end
+
+      def read_blob(book_sha, entry_path)
+        path = blob_path(book_sha, entry_path)
+        return nil unless File.file?(path)
+
+        data = File.binread(path)
+        data.force_encoding(Encoding::BINARY)
+        data
+      rescue StandardError
+        nil
+      end
+
+      def write_blob(book_sha, entry_path, bytes)
+        return unless book_sha
+
+        AtomicFileWriter.write(blob_path(book_sha, entry_path), bytes, binary: true)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+require_relative '../../../monitoring/perf_tracer.rb'
+require_relative '../../../output/terminal/terminal_sanitizer.rb'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Processes HTML content
+    class HTMLProcessor
+      def self.extract_title(html)
+        match = html.match(%r{<title[^>]*>([^<]+)</title>}i) ||
+                html.match(%r{<h[1-3][^>]*>([^<]+)</h[1-3]>}i)
+        clean_html(match[1]) if match
+      end
+
+      def self.html_to_text(html)
+        if Shoko::Adapters::Monitoring::PerfTracer.enabled?
+          Shoko::Adapters::Monitoring::PerfTracer.measure('xhtml.normalize') { normalize_html(html) }
+        else
+          normalize_html(html)
+        end
+      end
+
+      BLOCK_REPLACEMENTS = {
+        %r{</p>}i => "\n\n",
+        /<p[^>]*>/i => "\n\n",
+        /<br[^>]*>/i => "\n",
+        %r{</h[1-6]>}i => "\n\n",
+        /<h[1-6][^>]*>/i => "\n\n",
+        %r{</div>}i => "\n",
+        /<div[^>]*>/i => "\n",
+      }.freeze
+
+      private_constant :BLOCK_REPLACEMENTS
+
+      HTML_ENTITY_MAP = {
+        'nbsp' => ' ',
+        'ensp' => ' ',
+        'emsp' => ' ',
+        'thinsp' => ' ',
+        'shy' => '',
+        'mdash' => '—',
+        'ndash' => '–',
+        'hellip' => '…',
+        'ldquo' => '“',
+        'rdquo' => '”',
+        'lsquo' => '‘',
+        'rsquo' => '’',
+        'laquo' => '«',
+        'raquo' => '»',
+        'bull' => '•',
+        'middot' => '·',
+        'times' => '×',
+        'divide' => '÷',
+        'deg' => '°',
+        'copy' => '©',
+        'reg' => '®',
+        'trade' => '™',
+        'frac14' => '¼',
+        'frac12' => '½',
+        'frac34' => '¾',
+        'sup1' => '¹',
+        'sup2' => '²',
+        'sup3' => '³',
+      }.freeze
+
+      private_constant :HTML_ENTITY_MAP
+
+      def self.decode_entities(text)
+        str = text.to_s
+        return str if str.empty?
+
+        decoded = str.gsub(/&#x([0-9A-Fa-f]+);/) do |match|
+          [Regexp.last_match(1).to_i(16)].pack('U')
+        rescue StandardError
+          match
+        end
+
+        decoded = decoded.gsub(/&#(\d+);/) do |match|
+          [Regexp.last_match(1).to_i].pack('U')
+        rescue StandardError
+          match
+        end
+
+        decoded = decoded.gsub(/&([A-Za-z][A-Za-z0-9]+);/) do |match|
+          name = Regexp.last_match(1)
+          replacement = HTML_ENTITY_MAP[name] || HTML_ENTITY_MAP[name.downcase]
+          replacement.nil? ? match : replacement
+        end
+
+        # Decode the built-in XML entities (amp/lt/gt/quot/apos) last.
+        CGI.unescapeHTML(decoded).tr("\u00A0", ' ')
+      end
+
+      private_class_method def self.normalize_html(html)
+        text = html.dup
+        # Handle CDATA sections BEFORE removing other tags
+        text = handle_cdata_sections(text)
+        text = remove_scripts_and_styles(text)
+        text = replace_block_elements(text)
+        text = strip_tags(text)
+        text = decode_entities(text)
+        cleaned = clean_whitespace(text)
+        Shoko::Adapters::Output::Terminal::TerminalSanitizer.sanitize(
+          cleaned,
+          preserve_newlines: true,
+          preserve_tabs: false
+        )
+      end
+
+      private_class_method def self.handle_cdata_sections(text)
+        # Extract CDATA content before other processing
+        text.gsub(/<!\[CDATA\[(.*?)\]\]>/m, '\1')
+      end
+
+      private_class_method def self.remove_scripts_and_styles(text)
+        text.gsub!(%r{<script[^>]*>.*?</script>}mi, '')
+        text.gsub!(%r{<style[^>]*>.*?</style>}mi, '')
+        text
+      end
+
+      private_class_method def self.replace_block_elements(text)
+        BLOCK_REPLACEMENTS.each { |pattern, rep| text.gsub!(pattern, rep) }
+        text
+      end
+
+      private_class_method def self.strip_tags(text)
+        text.gsub!(/<[^>]+>/, '')
+        text
+      end
+
+      private_class_method def self.clean_whitespace(text)
+        text.delete!("\r")
+        text.gsub!(/\n{3,}/, "\n\n")
+        text.gsub!(/[ \t]+/, ' ')
+        text.strip
+      end
+
+      def self.clean_html(text)
+        decoded = decode_entities(text.to_s.strip)
+        Shoko::Adapters::Output::Terminal::TerminalSanitizer.sanitize(
+          decoded,
+          preserve_newlines: false,
+          preserve_tabs: false
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'zip'
+require 'rexml/document'
+
+require_relative 'opf_processor'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Lightweight extractor for common EPUB metadata (authors, year)
+    # Opens the EPUB zip and reads the OPF without loading chapter content.
+    class MetadataExtractor
+      def self.from_epub(path)
+        Zip::File.open(path) do |zip|
+          opf_path = find_opf_path(zip)
+          return {} unless opf_path
+
+          processor = OPFProcessor.new(opf_path, zip: zip)
+          meta = processor.extract_metadata
+          normalize(meta)
+        end
+      rescue StandardError
+        {}
+      end
+
+      def self.find_opf_path(zip)
+        container_xml = zip.read('META-INF/container.xml')
+        container = REXML::Document.new(container_xml)
+        rootfile = container.elements['//rootfile']
+        return nil unless rootfile
+
+        opf_path = rootfile.attributes['full-path']
+        zip.find_entry(opf_path) ? opf_path : nil
+      rescue StandardError
+        nil
+      end
+
+      def self.normalize(meta)
+        return {} unless meta.is_a?(Hash)
+
+        authors = Array(meta[:authors]).compact.map(&:to_s).reject(&:empty?)
+        {
+          authors: authors,
+          author_str: authors.join('; '),
+          year: (meta[:year] || '').to_s[0, 4],
+          title: meta[:title],
+          language: meta[:language],
+        }
+      end
+      private_class_method :find_opf_path, :normalize
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+require_relative '../xml_text_normalizer'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Reads OPF and related XML entries from a zip or filesystem path.
+    class OPFEntryReader
+      def initialize(opf_path, zip: nil)
+        @opf_path = opf_path
+        @opf_dir = File.dirname(opf_path)
+        @zip = zip
+      end
+
+      def zip?
+        !@zip.nil?
+      end
+
+      def read_raw(path)
+        zip? ? @zip.read(path) : File.read(path)
+      end
+
+      def read_entry(path)
+        normalize_xml_text(read_raw(path))
+      end
+
+      def safe_read_entry(path)
+        read_entry(path)
+      rescue StandardError
+        nil
+      end
+
+      def entry_exists?(path)
+        zip? ? !!@zip.find_entry(path) : File.exist?(path)
+      end
+
+      def join_path(href)
+        expand_path(@opf_dir, href)
+      end
+
+      def expand_path(base_dir, href)
+        return nil if href.nil? || href.to_s.empty?
+
+        if zip?
+          File.expand_path(File.join('/', base_dir, href), '/').sub(%r{^/}, '')
+        else
+          File.expand_path(File.join(base_dir, href))
+        end
+      end
+
+      def normalize_opf_relative_href(href)
+        return nil if href.nil? || href.to_s.empty?
+
+        joined = join_path(href)
+        return nil unless joined
+
+        Pathname.new(joined).relative_path_from(Pathname.new(@opf_dir)).to_s
+      rescue ArgumentError
+        href.to_s
+      end
+
+      def opf_relative_path(path)
+        return nil if path.nil? || path.to_s.empty?
+
+        Pathname.new(path).relative_path_from(Pathname.new(@opf_dir)).to_s
+      rescue ArgumentError
+        nil
+      end
+
+      def normalize_xml_text(content)
+        XmlTextNormalizer.normalize(content)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative '../html_processor'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Extracts metadata fields from an OPF document.
+    class OPFMetadataExtractor
+      def initialize(opf)
+        @opf = opf
+      end
+
+      def extract
+        metadata_element = @opf.elements['//metadata']
+        return {} unless metadata_element
+
+        @elements = metadata_element.elements
+        @metadata = {}
+
+        extract_title
+        extract_language
+        extract_authors
+        extract_year
+
+        @metadata
+      ensure
+        @elements = nil
+        @metadata = nil
+      end
+
+      private
+
+      def extract_title
+        raw_title = @elements['*[local-name()="title"]']&.text
+        return unless raw_title
+
+        title = HTMLProcessor.clean_html(raw_title.to_s).strip
+        @metadata[:title] = title unless title.empty?
+      end
+
+      def extract_language
+        lang_text = @elements['*[local-name()="language"]']&.text
+        return unless lang_text
+
+        @metadata[:language] = lang_text.include?('_') ? lang_text : "#{lang_text}_#{lang_text.upcase}"
+      end
+
+      def extract_authors
+        authors = []
+        @elements.each('*[local-name()="creator"]') do |creator|
+          txt = HTMLProcessor.clean_html(creator.text.to_s).strip
+          authors << txt unless txt.empty?
+        end
+        @metadata[:authors] = authors unless authors.empty?
+      end
+
+      def extract_year
+        date_elem = @elements['*[local-name()="date"]']
+        return unless date_elem
+
+        date_text = date_elem.text.to_s
+        match = date_text.match(/(\d{4})/)
+        @metadata[:year] = match[1] if match
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+
+require_relative 'navigation_label_resolver'
+require_relative 'navigation_list_item'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Tracks navigation entries/titles while walking a nav tree.
+    class OPFNavigationContext
+      attr_reader :toc_entries, :titles, :level
+
+      def self.root(source_path:, entry_reader:)
+        label_resolver = OPFNavigationLabelResolver.new(entry_reader: entry_reader, source_path: source_path)
+        new(label_resolver: label_resolver, level: 0, toc_entries: [], titles: {})
+      end
+
+      def initialize(label_resolver:, level:, toc_entries:, titles:)
+        @label_resolver = label_resolver
+        @level = level
+        @toc_entries = toc_entries
+        @titles = titles
+      end
+
+      def source_path
+        @label_resolver.source_path
+      end
+
+      def next_level
+        self.class.new(
+          label_resolver: @label_resolver,
+          level: @level + 1,
+          toc_entries: @toc_entries,
+          titles: @titles
+        )
+      end
+
+      def add_entry(title:, href:)
+        target_path, opf_href = @label_resolver.target_for(href: href)
+        @toc_entries << {
+          title: title,
+          href: href,
+          level: @level,
+          source_path: source_path,
+          target: target_path,
+          opf_href: opf_href,
+        }
+
+        return unless opf_href
+        return if @level.zero? && @titles.key?(opf_href)
+
+        @titles[opf_href] = title
+      end
+
+      def clean_label(text)
+        @label_resolver.clean_label(text)
+      end
+
+      def resolve_label(href:, title:)
+        @label_resolver.resolve(href: href, title: title)
+      end
+
+      def entry_for_nav_point(nav_point)
+        elements = nav_point.elements
+        href_attr = elements['content']&.attributes&.[]('src')
+        title = resolve_label(
+          href: href_attr,
+          title: clean_label(elements['navLabel/text']&.text.to_s)
+        )
+        [title, href_attr]
+      end
+
+      def entry_for_list_item(list_item)
+        details = OPFNavigationListItem.new(list_item, cleaner: self)
+        href_attr = details.href
+        title = resolve_label(href: href_attr, title: details.title)
+        [title, href_attr]
+      end
+
+      def to_result(result_class)
+        result_class.new(toc_entries: @toc_entries, titles: @titles)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative 'navigation_document_scanner'
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Caches anchor labels and heading queues for navigation fallbacks.
+    class OPFNavigationDocumentIndex
+      # Value object for indexed document content.
+      Document = Struct.new(:path, :content, keyword_init: true)
+      private_constant :Document
+
+      def initialize(entry_reader:, cleaner:)
+        @entry_reader = entry_reader
+        @scanner = OPFNavigationDocumentScanner.new(cleaner: cleaner)
+        @anchors = {}
+        @headings = {}
+      end
+
+      def anchor_label(path, anchor)
+        ensure_index(path)
+        @anchors[path][anchor]
+      end
+
+      def next_heading(path)
+        ensure_index(path)
+        queue = @headings[path]
+        return '' unless queue
+
+        queue.shift.to_s
+      end
+
+      def remove_heading(path, text)
+        cleaned = text.to_s.strip
+        return if cleaned.empty?
+
+        queue = heading_queue(path)
+        idx = queue&.index(cleaned)
+        queue.delete_at(idx) if idx
+      end
+
+      private
+
+      def ensure_index(path)
+        return if @anchors.key?(path)
+
+        content = @entry_reader.safe_read_entry(path)
+        index_document(Document.new(path: path, content: content))
+      end
+
+      def index_document(document)
+        path = document.path
+        return if @anchors.key?(path)
+
+        prepare_index(path)
+        apply_scan(path, @scanner.scan(document.content))
+      end
+
+      def prepare_index(path)
+        @anchors[path] = {}
+        @headings[path] = []
+      end
+
+      def apply_scan(path, scan_result)
+        @anchors[path].merge!(scan_result.anchors)
+        @headings[path].concat(scan_result.headings)
+      end
+
+      def heading_queue(path)
+        ensure_index(path)
+        @headings[path]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::BookSources::Epub::Parsers
+    # Scans document content for anchor and heading labels.
+    class OPFNavigationDocumentScanner
+      # Value object for extracted anchor and heading labels.
+      ScanResult = Struct.new(:anchors, :headings, keyword_init: true)
+      private_constant :ScanResult
+
+      def initialize(cleaner:)
+        @cleaner = cleaner
+        @anchor_regex = %r{<(h[1-6])[^>]*?(?:id|name|xml:id)\s*=\s*["']([^"']+)["'][^>]*>(.*?)</\1>}im
+        @heading_regex = %r{<(h[1-6])[^>]*>(.*?)</\1>}im
+      end
+
+      def scan(content)
+        return ScanResult.new(anchors: {}, headings: []) unless content
+
+        result = ScanResult.new(anchors: {}, headings: [])
+        scan_anchors(content, result.anchors)
+        scan_headings(content, result.headings)
+        result
+      end
+
+      private
+
+      def scan_anchors(content, anchors)
+        content.scan(@anchor_regex) { |_tag, anchor, text| store_anchor(anchors, anchor, text) }
+      end
+
+      def scan_headings(content, headings)
+        content.scan(@heading_regex) { |_tag, text| store_heading(headings, text) }
+      end
+
+      def store_anchor(anchors, anchor, text)
+        label = @cleaner.clean_label(text)
+        anchors[anchor] = label unless label.empty?
+      end
+
+      def store_heading(headings, text)
+        label = @cleaner.clean_label(text)
+        headings << label unless label.empty?
+      end
+    end
+  end
+end