shoko 0.1.3 → 0.1.5

data/lib/shoko/core/book_formats/fb2/metadata_parser.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Core
+    module BookFormats
+      module Fb2
+        # Canonical parser for FB2 title-info metadata fields.
+        class MetadataParser
+          class << self
+            # @param doc [REXML::Document]
+            # @return [Hash] canonical metadata hash
+            def parse_document(doc)
+              title_info = locate_title_info(doc)
+              unless title_info
+                raise Shoko::MalformedMetadataInputError, 'FB2 metadata missing description/title-info'
+              end
+
+              {
+                title: extract_text(title_info, 'book-title'),
+                authors: extract_authors(title_info),
+                year: extract_year(title_info),
+                language: extract_text(title_info, 'lang'),
+              }
+            end
+
+            private
+
+            def locate_title_info(doc)
+              find_element(doc, 'description/title-info') ||
+                find_element(doc, 'FictionBook/description/title-info')
+            end
+
+            def find_element(context, path)
+              parts = path.to_s.split('/')
+              current = context.is_a?(REXML::Document) ? context.root : context
+              return nil unless current
+
+              parts.each do |part|
+                current = current.elements.detect { |el| el.name.to_s.casecmp(part).zero? }
+                return nil unless current
+              end
+              current
+            end
+
+            def extract_text(parent, tag)
+              return nil unless parent
+
+              element = parent.elements[tag]
+              return nil unless element
+
+              text = collect_text(element).strip
+              text.empty? ? nil : text
+            end
+
+            def collect_text(element)
+              text = +''
+              element.each_child do |child|
+                case child
+                when REXML::Text then text << child.value
+                when REXML::Element then text << collect_text(child)
+                end
+              end
+              text
+            end
+
+            def extract_authors(title_info)
+              authors = []
+              title_info.elements.each('author') do |author_element|
+                first = extract_text(author_element, 'first-name')
+                middle = extract_text(author_element, 'middle-name')
+                last = extract_text(author_element, 'last-name')
+                nickname = extract_text(author_element, 'nickname')
+
+                parts = [first, middle, last].compact
+                name = parts.empty? ? nickname : parts.join(' ')
+                authors << name if name && !name.empty?
+              end
+              authors
+            end
+
+            def extract_year(title_info)
+              date_element = title_info.elements['date']
+              return nil unless date_element
+
+              raw = date_element.attributes['value'] || collect_text(date_element)
+              return nil unless raw
+
+              match = raw.match(/\d{4}/)
+              match && match[0]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/book_formats/format_registry.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Core
+    module BookFormats
+      # Central registry mapping ebook file extensions to their importer classes,
+      # metadata extractors, and content parser factories.
+      #
+      # Format modules self-register on load:
+      #   FormatRegistry.register('.epub', importer_class: EpubImporter, ...)
+      #
+      # Consumers query:
+      #   FormatRegistry.importer_for(path)
+      #   FormatRegistry.supported_extension?(path)
+      module FormatRegistry
+        Entry = Struct.new(:importer_class, :metadata_extractor, :content_parser_factory, keyword_init: true)
+        private_constant :Entry
+        LazyResolver = Struct.new(:resolver, keyword_init: true) do
+          def resolve
+            resolver.call
+          end
+        end
+
+        @formats = {}
+
+        class << self
+          # Register a format by its file extension.
+          #
+          # @param extension [String] e.g. '.epub', '.fb2', '.fb2.zip'
+          # @param importer_class [Class, LazyResolver] importer class or lazy resolver
+          # @param metadata_extractor [Object, LazyResolver, nil] extractor or lazy resolver
+          # @param content_parser_factory [Proc, nil] ->(raw, logger:) { parser }
+          def register(extension, importer_class:, metadata_extractor: nil, content_parser_factory: nil)
+            @formats[extension.downcase] = Entry.new(
+              importer_class: importer_class,
+              metadata_extractor: metadata_extractor,
+              content_parser_factory: content_parser_factory
+            )
+          end
+
+          # Return the importer class for the given file path.
+          #
+          # @param path [String] file path
+          # @return [Class, nil]
+          def importer_for(path)
+            resolve_entry_value(entry_for(path), :importer_class)
+          end
+
+          # Return the metadata extractor for the given file path.
+          #
+          # @param path [String] file path
+          # @return [Object, nil]
+          def metadata_extractor_for(path)
+            resolve_entry_value(entry_for(path), :metadata_extractor)
+          end
+
+          # Return the content parser factory for the given file path.
+          #
+          # @param path [String] file path
+          # @return [Proc, nil]
+          def content_parser_factory_for(path)
+            resolve_entry_value(entry_for(path), :content_parser_factory)
+          end
+
+          # Check if the given file path has a supported ebook extension.
+          #
+          # @param path [String] file path
+          # @return [Boolean]
+          def supported_extension?(path)
+            !entry_for(path).nil?
+          end
+
+          # Return all registered extensions.
+          #
+          # @return [Array<String>]
+          def supported_extensions
+            @formats.keys
+          end
+
+          # Compatibility helper that checks only registered extensions.
+          #
+          # @param path [String] file path
+          # @return [Boolean]
+          def book_file?(path)
+            supported_extension?(path)
+          end
+
+          # Return the format key (extension) for a path, for tagging chapters.
+          #
+          # @param path [String]
+          # @return [Symbol, nil] e.g. :epub, :fb2
+          def format_key_for(path)
+            ext = detect_extension(path)
+            return nil unless ext
+
+            ext.delete_prefix('.').tr('.', '_').to_sym
+          end
+
+          private
+
+          def entry_for(path)
+            ext = detect_extension(path)
+            return nil unless ext
+
+            @formats[ext]
+          end
+
+          # Allow lazy registration values via zero-arity resolvers.
+          # This keeps heavyweight format classes out of bootstrap until needed.
+          def resolve_entry_value(entry, field)
+            return nil unless entry
+
+            value = case field
+                    when :importer_class
+                      entry.importer_class
+                    when :metadata_extractor
+                      entry.metadata_extractor
+                    when :content_parser_factory
+                      entry.content_parser_factory
+                    else
+                      raise ArgumentError, "Unsupported format registry field: #{field.inspect}"
+                    end
+            return value unless lazy_resolver?(value)
+
+            resolved = value.resolve
+            return resolved if resolved.nil?
+
+            case field
+            when :importer_class
+              entry.importer_class = resolved
+            when :metadata_extractor
+              entry.metadata_extractor = resolved
+            when :content_parser_factory
+              entry.content_parser_factory = resolved
+            end
+            resolved
+          end
+
+          def lazy_resolver?(value)
+            value.is_a?(LazyResolver)
+          end
+
+          # Detect the registered extension for a path.
+          # Tries compound extensions first (e.g. '.fb2.zip') then simple.
+          def detect_extension(path)
+            lower = path.to_s.downcase
+            # Try compound extensions first (longest match)
+            @formats.keys.sort_by { |k| -k.length }.each do |ext|
+              return ext if lower.end_with?(ext)
+            end
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/book_formats/kindle/exth_parser.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Core
+    module BookFormats
+      module Kindle
+        # Parses the EXTH (Extended Header) metadata block from a Mobipocket file.
+        #
+        # EXTH header layout:
+        #   Offset  Size  Field
+        #   0       4     Identifier ("EXTH")
+        #   4       4     Header length (total size including records)
+        #   8       4     Record count
+        #   12+     var   EXTH records (type + length + data each)
+        #
+        # Each EXTH record:
+        #   Offset  Size  Field
+        #   0       4     Record type (UInt32)
+        #   4       4     Record length (total including type+length fields)
+        #   8       N-8   Record data
+        class ExthParser
+          EXTH_MAGIC = 'EXTH'
+
+          # Well-known EXTH record type IDs
+          AUTHOR           = 100
+          PUBLISHER        = 101
+          DESCRIPTION      = 103
+          ISBN             = 104
+          SUBJECT          = 105
+          PUBLISHING_DATE  = 106
+          CONTRIBUTOR      = 108
+          RIGHTS           = 109
+          ASIN             = 113
+          LANGUAGE         = 524
+          UPDATED_TITLE    = 503
+          COVER_OFFSET     = 201
+          THUMBNAIL_OFFSET = 202
+          CREATOR_SOFTWARE = 204
+
+          # String-valued record types
+          STRING_TYPES = [
+            AUTHOR, PUBLISHER, DESCRIPTION, ISBN, SUBJECT,
+            PUBLISHING_DATE, CONTRIBUTOR, RIGHTS, ASIN, LANGUAGE,
+            UPDATED_TITLE, CREATOR_SOFTWARE
+          ].freeze
+
+          # @return [Hash{Integer => Array<String>}] parsed records keyed by type ID
+          attr_reader :records
+
+          # @param data [String] raw bytes starting at the EXTH header
+          # @param encoding_name [String] text encoding for string values (default UTF-8)
+          def initialize(data, encoding_name: 'UTF-8')
+            @data = data.b
+            @encoding_name = encoding_name
+            @records = {}
+            parse
+          end
+
+          # @return [String, nil] author name(s)
+          def author
+            first_string(AUTHOR)
+          end
+
+          # @return [Array<String>] all author entries
+          def authors
+            strings(AUTHOR)
+          end
+
+          # @return [String, nil] updated title (preferred over MOBI full name)
+          def updated_title
+            first_string(UPDATED_TITLE)
+          end
+
+          # @return [String, nil] publisher
+          def publisher
+            first_string(PUBLISHER)
+          end
+
+          # @return [String, nil] description
+          def description
+            first_string(DESCRIPTION)
+          end
+
+          # @return [String, nil] ISBN
+          def isbn
+            first_string(ISBN)
+          end
+
+          # @return [String, nil] publishing date
+          def publishing_date
+            first_string(PUBLISHING_DATE)
+          end
+
+          # @return [String, nil] language
+          def language
+            first_string(LANGUAGE)
+          end
+
+          # @return [String, nil] ASIN
+          def asin
+            first_string(ASIN)
+          end
+
+          # @return [String, nil] subject/genre
+          def subject
+            first_string(SUBJECT)
+          end
+
+          private
+
+          def parse
+            return if @data.bytesize < 12
+
+            magic = @data.byteslice(0, 4)
+            return unless magic == EXTH_MAGIC
+
+            record_count = @data.byteslice(8, 4).unpack1('N')
+            offset = 12
+
+            record_count.times do
+              break if offset + 8 > @data.bytesize
+
+              type = @data.byteslice(offset, 4).unpack1('N')
+              length = @data.byteslice(offset + 4, 4).unpack1('N')
+
+              # Sanity check: length must be at least 8 (type + length fields)
+              break if length < 8 || offset + length > @data.bytesize
+
+              data_length = length - 8
+              raw_value = @data.byteslice(offset + 8, data_length)
+
+              value = if STRING_TYPES.include?(type)
+                        decode_string(raw_value)
+                      else
+                        raw_value
+                      end
+
+              (@records[type] ||= []) << value
+              offset += length
+            end
+          end
+
+          def decode_string(raw)
+            raw.force_encoding(@encoding_name)
+            raw.encode('UTF-8', invalid: :replace, undef: :replace, replace: '').strip
+          rescue Shoko::Error
+            raw.force_encoding('UTF-8')
+            raw.encode('UTF-8', invalid: :replace, undef: :replace, replace: '').strip
+          end
+
+          def first_string(type)
+            values = @records[type]
+            return nil unless values&.any?
+
+            val = values.first
+            val.is_a?(String) && !val.empty? ? val : nil
+          end
+
+          def strings(type)
+            values = @records[type]
+            return [] unless values
+
+            values.select { |v| v.is_a?(String) && !v.empty? }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/book_formats/kindle/kindle_content_parser.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../epub/xhtml_content_parser'
+
+module Shoko
+  module Core
+    module BookFormats
+      module Kindle
+        # Content parser for Kindle/Mobipocket chapter fragments.
+        #
+        # Delegates to the proven XHTMLContentParser since MOBI/AZW content
+        # is HTML and AZW3/KF8 content is XHTML — both are valid inputs
+        # for the existing EPUB parser.
+        class KindleContentParser
+          # @param html [String] HTML/XHTML chapter fragment
+          # @param logger [Object, nil] optional logger
+          def initialize(html, logger: nil)
+            @delegate = Core::BookFormats::Epub::XHTMLContentParser.new(html, logger: logger)
+          end
+
+          # Parse the chapter HTML into semantic content blocks.
+          #
+          # @return [Array<Core::Models::ContentBlock>]
+          def parse
+            @delegate.parse
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/book_formats/kindle/kindle_metadata_extractor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative 'pdb_header_parser'
+require_relative 'mobi_header_parser'
+require_relative 'exth_parser'
+require_relative 'metadata_parser'
+require_relative '../../ports/outbound/path_ops'
+
+module Shoko
+  module Core
+    module BookFormats
+      module Kindle
+        # Lightweight metadata extractor for Kindle/Mobipocket files.
+        # Implements the `self.from_file(path)` interface used by FormatRegistry.
+        #
+        # Reads only the PDB header and record 0 (MOBI + EXTH headers) to
+        # quickly extract title, author, year, and language without
+        # decompressing the full text content.
+        module KindleMetadataExtractor
+          class << self
+            # Extract metadata from a .mobi, .azw, or .azw3 file.
+            #
+            # @param path [String] path to the ebook file
+            # @param file_reader [#call, nil] binary file reader dependency
+            # @param path_ops [#basename, nil] path utility dependency
+            # @return [Hash] { title:, authors:, author_str:, year:, language: }
+            def from_file(path, file_reader: nil, path_ops: nil, **_)
+              raise ArgumentError, 'file_reader is required' unless file_reader
+              unless path_ops.is_a?(Shoko::Core::Ports::Outbound::PathOps)
+                raise ArgumentError, 'path_ops must implement Core::Ports::Outbound::PathOps'
+              end
+
+              data = file_reader.call(path).to_s
+              pdb = PdbHeaderParser.new(data)
+              record0 = pdb.record_data(0)
+              mobi = MobiHeaderParser.new(record0)
+              exth = nil
+
+              if mobi.has_exth?
+                exth_data = record0.byteslice(mobi.exth_offset..)
+                exth = ExthParser.new(exth_data, encoding_name: mobi.encoding_name)
+              end
+
+              canonical = MetadataParser.parse(
+                mobi: mobi,
+                exth: exth,
+                fallback_title: fallback_title(path, path_ops: path_ops)
+              )
+              authors = Array(canonical[:authors]).map(&:to_s).reject(&:empty?)
+
+              {
+                title: canonical[:title],
+                authors: authors,
+                author_str: authors.empty? ? nil : authors.join('; '),
+                year: canonical[:year],
+                language: canonical[:language]
+              }.compact
+            rescue Shoko::MalformedMetadataInputError
+              raise
+            rescue Shoko::Error, ArgumentError, TypeError, IOError, SystemCallError => e
+              raise Shoko::MalformedMetadataInputError, "Kindle metadata extraction failed for #{path}: #{e.message}"
+            end
+
+            private
+
+            def fallback_title(path, path_ops: nil)
+              basename = path_ops.basename(path).to_s
+              # Strip known extensions
+              %w[.mobi .azw3 .azw].each do |ext|
+                basename = basename[0..-(ext.length + 1)] if basename.downcase.end_with?(ext)
+              end
+              basename.tr('_', ' ').strip
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/book_formats/kindle/metadata_parser.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Core
+    module BookFormats
+      module Kindle
+        # Canonical parser for Kindle metadata from MOBI/EXTH fields.
+        class MetadataParser
+          class << self
+            # @param mobi [Object] Parsed MOBI header
+            # @param exth [Object, nil] Parsed EXTH metadata
+            # @param fallback_title [String, nil] Fallback title from file name
+            # @return [Hash] canonical metadata hash
+            def parse(mobi:, exth:, fallback_title:)
+              {
+                title: resolve_title(mobi, exth, fallback_title),
+                authors: resolve_authors(exth),
+                year: resolve_year(exth),
+                language: normalize_text(exth&.language),
+              }
+            rescue Shoko::Error
+              {
+                title: normalize_text(fallback_title),
+                authors: [],
+                year: nil,
+                language: nil,
+              }
+            end
+
+            private
+
+            def resolve_title(mobi, exth, fallback_title)
+              normalize_text(exth&.updated_title) ||
+                normalize_text(mobi&.full_name) ||
+                normalize_text(fallback_title)
+            end
+
+            def resolve_authors(exth)
+              Array(exth&.authors).map { |author| normalize_text(author) }.compact
+            end
+
+            def resolve_year(exth)
+              date = exth&.publishing_date
+              return nil unless date
+
+              match = date.to_s.match(/\d{4}/)
+              match && match[0]
+            end
+
+            def normalize_text(value)
+              return nil unless value
+
+              text = value.to_s.strip
+              text.empty? ? nil : text
+            end
+          end
+        end
+      end
+    end
+  end
+end