brand_logo 1.0.0 → 2.0.0

data/lib/brand_logo/image_probe.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'fastimage'
+require 'stringio'
+
+module BrandLogo
+  module ImageProbe
+    extend T::Sig
+
+    BYTES = 65_536
+
+    Result = Data.define(:format, :dimensions)
+
+    sig { params(body: String).returns(T.nilable(Result)) }
+    def self.analyze(body)
+      image = FastImage.new(StringIO.new(body), raise_on_failure: false)
+      format = ImageFormat.from_fastimage(image.type)
+      return nil unless format
+
+      width, height = image.size
+      Result.new(format: format, dimensions: Dimensions.new(width: width, height: height))
+    # FastImage parses untrusted bytes and can fail outside its own error list.
+    rescue StandardError => e
+      Logging.logger.warn("ImageProbe: unreadable image (#{e.class}: #{e.message})")
+      nil
+    end
+  end
+end

data/lib/brand_logo/logging.rb

@@ -2,15 +2,9 @@
 # typed: strict
 
 require 'logger'
-require 'sorbet-runtime'
+require_relative 'sorbet'
 
 module BrandLogo
-  # Centralized logging for the gem.
-  # Replaces the DebugLogger module's debug boolean pattern.
-  #
-  # Usage:
-  #   BrandLogo::Logging.logger.level = Logger::DEBUG  # enable verbose output
-  #   BrandLogo::Logging.logger = MyCustomLogger.new   # inject custom logger
   module Logging
     extend T::Sig
 

data/lib/brand_logo/lookup.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  class Lookup
+    extend T::Sig
+
+    STAGES = T.let(%i[document remote external].freeze, T::Array[Symbol])
+
+    sig { params(context: Context, strategies: T::Array[Strategies::Base], ranker: Ranker).void }
+    def initialize(context:, strategies:, ranker:)
+      @context = context
+      @strategies = strategies
+      @ranker = ranker
+    end
+
+    sig { returns(T.nilable(Icon)) }
+    def best
+      icons = T.let([], T::Array[Icon])
+      STAGES.each do |stage|
+        break if @context.deadline.expired?
+        next if skip?(stage, icons)
+
+        icons = run(stage, icons)
+        winner = icons.first
+        return winner if winner && @ranker.good_enough?(winner)
+      end
+      icons.first
+    end
+
+    sig { returns(T::Array[Icon]) }
+    def all
+      STAGES.reduce(T.let([], T::Array[Icon])) do |icons, stage|
+        @context.deadline.expired? ? icons : run(stage, icons)
+      end
+    end
+
+    sig { returns(T::Boolean) }
+    def timed_out?
+      @context.deadline.expired?
+    end
+
+    private
+
+    sig { params(stage: Symbol, icons: T::Array[Icon]).returns(T::Boolean) }
+    def skip?(stage, icons)
+      stage == :external && icons.any? { |icon| @ranker.usable?(icon) }
+    end
+
+    sig { params(stage: Symbol, previous: T::Array[Icon]).returns(T::Array[Icon]) }
+    def run(stage, previous)
+      seen = previous.to_set(&:url)
+      candidates = collect(stage).uniq(&:url).reject { |icon| seen.include?(icon.url) }
+      BrandLogo::Logging.logger.debug("[#{@context.domain}] #{stage}: #{candidates.size} new candidate(s)")
+      @ranker.rank(previous + parallel(candidates) { |icon| measure(icon) }.compact)
+    end
+
+    sig { params(stage: Symbol).returns(T::Array[Icon]) }
+    def collect(stage)
+      strategies = @strategies.select { |strategy| strategy.stage == stage }
+      parallel(strategies) { |strategy| strategy.call(@context) }.flatten
+    end
+
+    sig { params(icon: Icon).returns(T.nilable(Icon)) }
+    def measure(icon)
+      result = @context.probe(icon.url)
+      return nil unless result
+
+      icon.with(format: result.format, dimensions: measured_dimensions(icon, result))
+    end
+
+    # FastImage reads only the first entry of an .ico, which is often smaller than the declared largest one.
+    sig { params(icon: Icon, result: ImageProbe::Result).returns(Dimensions) }
+    def measured_dimensions(icon, result)
+      measured = result.dimensions
+      return icon.dimensions unless measured.known?
+      return [measured, icon.dimensions].max_by(&:area) || measured if result.format == :ico
+
+      measured
+    end
+
+    sig do
+      type_parameters(:I, :O)
+        .params(
+          items: T::Array[T.type_parameter(:I)],
+          block: T.proc.params(item: T.type_parameter(:I)).returns(T.type_parameter(:O))
+        )
+        .returns(T::Array[T.type_parameter(:O)])
+    end
+    def parallel(items, &block)
+      Concurrency.map(items, size: @context.config.concurrency, &block)
+    end
+  end
+end

data/lib/brand_logo/page.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'nokogiri'
+
+module BrandLogo
+  Page = Data.define(:url, :document, :base_url) do
+    extend T::Sig
+
+    sig { params(context: Context).returns(T.nilable(Page)) }
+    def self.fetch(context)
+      domain = context.domain
+      ["https://#{domain}", "https://www.#{domain}", "http://#{domain}"].each do |candidate|
+        response = context.get(candidate)
+        return build(response) if response
+      end
+      nil
+    end
+
+    sig { params(response: Http::Response).returns(T.nilable(Page)) }
+    def self.build(response)
+      document = Nokogiri::HTML5(response.body)
+      declared = document.at_css('base[href]')&.[]('href')
+      base_url = UrlResolver.resolve(declared, response.url) || response.url
+      new(url: response.url, document: document, base_url: base_url)
+    rescue ArgumentError => e
+      Logging.logger.warn("Page: cannot parse #{response.url}: #{e.message}")
+      nil
+    end
+    private_class_method :build
+
+    sig { params(href: T.nilable(String)).returns(T.nilable(String)) }
+    def resolve(href)
+      UrlResolver.resolve(href, base_url)
+    end
+  end
+end

data/lib/brand_logo/ranker.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  class Ranker
+    extend T::Sig
+
+    KIND_TIERS = T.let({
+      mask: 3, monochrome: 3, social: 2, tile: 1
+    }.freeze, T::Hash[Symbol, Integer])
+    UNUSABLE_TIER = 2
+    SCHEMES = T.let({
+      dark: /prefers-color-scheme\s*:\s*dark/i, light: /prefers-color-scheme\s*:\s*light/i
+    }.freeze, T::Hash[Symbol, Regexp])
+    DEFAULT_GOOD_SIZE = 128
+    MAX_ASPECT_RATIO = 1.2
+
+    sig { params(config: Config).void }
+    def initialize(config)
+      @config = config
+    end
+
+    sig { params(icons: T::Array[Icon]).returns(T::Array[Icon]) }
+    def rank(icons)
+      icons.select { |icon| valid?(icon) }
+           .each_with_index
+           .sort_by { |icon, index| [*penalty(icon), index] }
+           .map(&:first)
+    end
+
+    sig { params(icon: Icon).returns(T::Boolean) }
+    def usable?(icon)
+      valid?(icon) && KIND_TIERS.fetch(icon.kind, 0) < UNUSABLE_TIER
+    end
+
+    sig { params(icon: Icon).returns(T::Boolean) }
+    def good_enough?(icon)
+      return false unless usable?(icon)
+      return false if @config.prefer == :square && non_square?(icon)
+
+      icon.svg? || icon.dimensions.side >= (@config.target_size || DEFAULT_GOOD_SIZE)
+    end
+
+    private
+
+    sig { params(icon: Icon).returns(T::Boolean) }
+    def valid?(icon)
+      return false if icon.format.nil?
+      return @config.allow_svg if icon.svg?
+
+      within_limits?(icon.dimensions)
+    end
+
+    sig { params(dims: Dimensions).returns(T::Boolean) }
+    def within_limits?(dims)
+      min = @config.min_size
+      max = @config.max_size
+      (min.nil? || dims.at_least?(min)) && (max.nil? || dims.at_most?(max))
+    end
+
+    sig { params(icon: Icon).returns(T::Array[Numeric]) }
+    def penalty(icon)
+      [KIND_TIERS.fetch(icon.kind, 0), scheme_penalty(icon), *preference_penalty(icon), *size_penalty(icon)]
+    end
+
+    sig { params(icon: Icon).returns(Integer) }
+    def scheme_penalty(icon)
+      wanted = @config.color_scheme
+      return media_mentions?(icon, :dark) ? 1 : 0 unless wanted
+
+      opposite = wanted == :dark ? :light : :dark
+      return 0 if media_mentions?(icon, wanted)
+
+      media_mentions?(icon, opposite) ? 2 : 1
+    end
+
+    sig { params(icon: Icon, scheme: Symbol).returns(T::Boolean) }
+    def media_mentions?(icon, scheme)
+      SCHEMES.fetch(scheme).match?(icon.media.to_s)
+    end
+
+    sig { params(icon: Icon).returns(T::Array[Integer]) }
+    def preference_penalty(icon)
+      case @config.prefer
+      when :svg then [icon.svg? ? 0 : 1]
+      when :square then [non_square?(icon) ? 1 : 0, icon.svg? ? 0 : 1]
+      else []
+      end
+    end
+
+    sig { params(icon: Icon).returns(T::Boolean) }
+    def non_square?(icon)
+      w, h = icon.dimensions.to_pair
+      return false unless w && h
+
+      [w, h].max.fdiv([w, h].min) > MAX_ASPECT_RATIO
+    end
+
+    sig { params(icon: Icon).returns(T::Array[Numeric]) }
+    def size_penalty(icon)
+      target = @config.target_size
+      return [-area(icon)] unless target
+
+      side = icon.svg? ? target : icon.dimensions.side
+      return [0, target / 2.0, -area(icon)] if side.zero?
+
+      [side < target ? 1 : 0, (side - target).abs, -area(icon)]
+    end
+
+    sig { params(icon: Icon).returns(Numeric) }
+    def area(icon)
+      icon.svg? ? Float::INFINITY : icon.dimensions.area
+    end
+  end
+end

data/lib/brand_logo/sorbet.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+# typed: true
+
+begin
+  require 'sorbet-runtime'
+rescue LoadError
+  require_relative 'sorbet_shim'
+end

data/lib/brand_logo/sorbet_shim.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# typed: ignore
+
+# No-op stand-in for sorbet-runtime so host apps are not forced to depend on it.
+# Signatures are only enforced statically (`srb tc`); `sig` blocks are never evaluated.
+module T
+  module Sig
+    def sig(*) = nil
+  end
+
+  module Helpers
+    def abstract! = nil
+    def interface! = nil
+  end
+
+  module Boolean; end
+
+  module Generic
+    def [](*) = self
+  end
+
+  module Array; extend Generic; end
+  module Hash; extend Generic; end
+  module Range; extend Generic; end
+
+  class << self
+    def let(value, _type) = value
+    def cast(value, _type) = value
+
+    def must(value)
+      raise TypeError, 'Passed `nil` into T.must' if value.nil?
+
+      value
+    end
+
+    def nilable(*) = nil
+    def any(*) = nil
+    def untyped = nil
+    def class_of(*) = nil
+    def noreturn = nil
+    def type_parameter(*) = nil
+    def proc = nil
+  end
+end

data/lib/brand_logo/strategies/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  module Strategies
+    module Base
+      extend T::Sig
+      extend T::Helpers
+
+      interface!
+
+      sig { abstract.returns(Symbol) }
+      def stage; end
+
+      sig { abstract.params(context: Context).returns(T::Array[Icon]) }
+      def call(context); end
+    end
+  end
+end

data/lib/brand_logo/strategies/browserconfig.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  module Strategies
+    class Browserconfig
+      extend T::Sig
+      include Base
+
+      TILES = T.let({
+        'square70x70logo' => [70, 70],
+        'square150x150logo' => [150, 150],
+        'square310x310logo' => [310, 310],
+        'wide310x150logo' => [310, 150]
+      }.freeze, T::Hash[String, [Integer, Integer]])
+
+      sig { override.returns(Symbol) }
+      def stage
+        :remote
+      end
+
+      sig { override.params(context: Context).returns(T::Array[Icon]) }
+      def call(context)
+        response = fetch_config(context)
+        document = response && parse(response)
+        return [] unless response && document
+
+        document.xpath('//*').filter_map { |node| build(node, response.url) }
+      end
+
+      private
+
+      sig { params(context: Context).returns(T.nilable(Http::Response)) }
+      def fetch_config(context)
+        page = context.page
+        return nil unless page
+
+        declared = page.document.at_css('meta[name="msapplication-config"]')&.[]('content').to_s.strip
+        url = page.resolve(declared) unless declared.casecmp?('none')
+        url && context.get(url)
+      end
+
+      sig { params(response: Http::Response).returns(T.nilable(Nokogiri::XML::Document)) }
+      def parse(response)
+        document = Nokogiri::XML(response.body, &:strict)
+        document.remove_namespaces!
+        document
+      rescue Nokogiri::XML::SyntaxError => e
+        Logging.logger.warn("Browserconfig: invalid XML at #{response.url}: #{e.message}")
+        nil
+      end
+
+      sig { params(node: Nokogiri::XML::Node, config_url: String).returns(T.nilable(Icon)) }
+      def build(node, config_url)
+        size = TILES[node.name.downcase]
+        url = UrlResolver.resolve(node['src'], config_url) if size
+        return nil unless size && url
+
+        width, height = size
+        Icon.new(
+          url: url,
+          source: :browserconfig,
+          kind: :tile,
+          format: ImageFormat.from_url(url),
+          dimensions: Dimensions.new(width: width, height: height)
+        )
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/duckduckgo.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  module Strategies
+    class Duckduckgo
+      extend T::Sig
+      include Base
+
+      sig { override.returns(Symbol) }
+      def stage
+        :external
+      end
+
+      sig { override.params(context: Context).returns(T::Array[Icon]) }
+      def call(context)
+        [Icon.new(url: "https://icons.duckduckgo.com/ip3/#{context.domain}.ico", source: :duckduckgo)]
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/google.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'cgi'
+
+module BrandLogo
+  module Strategies
+    # Google's favicon service answers 404 for unknown domains, which the probe drops.
+    class Google
+      extend T::Sig
+      include Base
+
+      SIZE = 256
+
+      sig { override.returns(Symbol) }
+      def stage
+        :external
+      end
+
+      sig { override.params(context: Context).returns(T::Array[Icon]) }
+      def call(context)
+        [Icon.new(
+          url: "https://www.google.com/s2/favicons?domain=#{CGI.escape(context.domain)}&sz=#{SIZE}",
+          source: :google
+        )]
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/json_ld.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'json'
+
+module BrandLogo
+  module Strategies
+    class JsonLd
+      extend T::Sig
+      include Base
+
+      ORGANIZATION_TYPES = T.let(%w[Organization Corporation NGO LocalBusiness Brand].freeze, T::Array[String])
+      ORGANIZATION_SUFFIXES = T.let(%w[Organization Business Store Brand].freeze, T::Array[String])
+      OWNER_KEYS = T.let(%w[publisher brand].freeze, T::Array[String])
+
+      sig { override.returns(Symbol) }
+      def stage
+        :document
+      end
+
+      sig { override.params(context: Context).returns(T::Array[Icon]) }
+      def call(context)
+        page = context.page
+        return [] unless page
+
+        logos = []
+        page.document.css('script[type="application/ld+json"]').each do |script|
+          collect(JSON.parse(script.text), false, logos)
+        rescue JSON::ParserError => e
+          Logging.logger.warn("JsonLd: invalid JSON at #{page.url}: #{e.message}")
+        end
+        logos.filter_map { |logo| build(page, logo) }
+      end
+
+      private
+
+      sig { params(node: T.untyped, owner: T::Boolean, logos: T::Array[T.untyped]).void }
+      def collect(node, owner, logos)
+        case node
+        when ::Array
+          node.each { |child| collect(child, owner, logos) }
+        when ::Hash
+          logos.concat(declared_logos(node)) if owner || organization?(node['@type'])
+          node.each { |key, child| collect(child, OWNER_KEYS.include?(key), logos) }
+        end
+      end
+
+      sig { params(node: T::Hash[String, T.untyped]).returns(T::Array[T.untyped]) }
+      def declared_logos(node)
+        declared = node['logo']
+        declared.is_a?(::Array) ? declared : [declared].compact
+      end
+
+      sig { params(types: T.untyped).returns(T::Boolean) }
+      def organization?(types)
+        Array(types).any? do |type|
+          name = type.to_s.split(%r{[/:#]}).last.to_s
+          ORGANIZATION_TYPES.include?(name) || name.end_with?(*ORGANIZATION_SUFFIXES)
+        end
+      end
+
+      sig { params(page: Page, logo: T.untyped).returns(T.nilable(Icon)) }
+      def build(page, logo)
+        declared = logo.is_a?(::Hash) ? (logo['url'] || logo['contentUrl']) : logo
+        url = page.resolve(declared) if declared.is_a?(String)
+        return nil unless url
+
+        Icon.new(url: url, source: :json_ld, kind: :logo, format: format_of(logo, url), dimensions: dimensions(logo))
+      end
+
+      sig { params(logo: T.untyped, url: String).returns(T.nilable(Symbol)) }
+      def format_of(logo, url)
+        mime = logo['encodingFormat'] if logo.is_a?(::Hash)
+        ImageFormat.from_mime(mime) || ImageFormat.from_url(url)
+      end
+
+      sig { params(logo: T.untyped).returns(Dimensions) }
+      def dimensions(logo)
+        return Dimensions.new unless logo.is_a?(::Hash)
+
+        Dimensions.new(width: pixels(logo['width']), height: pixels(logo['height']))
+      end
+
+      sig { params(value: T.untyped).returns(T.nilable(Integer)) }
+      def pixels(value)
+        number = value.is_a?(Numeric) ? value.to_i : value.to_s[/\A\d+/]&.to_i
+        number if number&.positive?
+      end
+    end
+  end
+end

data/lib/brand_logo/strategies/link_tag.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  module Strategies
+    class LinkTag
+      extend T::Sig
+      include Base
+
+      APPLE_TOUCH = T.let(%w[apple-touch-icon apple-touch-icon-precomposed].freeze, T::Array[String])
+
+      sig { override.returns(Symbol) }
+      def stage
+        :document
+      end
+
+      sig { override.params(context: Context).returns(T::Array[Icon]) }
+      def call(context)
+        page = context.page
+        return [] unless page
+
+        page.document.css('link[rel]').filter_map { |link| build(page, link) } << favicon(page)
+      end
+
+      private
+
+      sig { params(page: Page, link: Nokogiri::XML::Element).returns(T.nilable(Icon)) }
+      def build(page, link)
+        kind = kind_of(link['rel'].to_s.downcase.split)
+        url = page.resolve(link['href'])
+        return nil unless kind && url
+
+        Icon.new(
+          url: url,
+          source: :link_tag,
+          kind: kind,
+          format: ImageFormat.from_mime(link['type']) || ImageFormat.from_url(url),
+          dimensions: Dimensions.parse(link['sizes']),
+          media: link['media']
+        )
+      end
+
+      sig { params(tokens: T::Array[String]).returns(T.nilable(Symbol)) }
+      def kind_of(tokens)
+        if tokens.include?('mask-icon') then :mask
+        elsif tokens.intersect?(APPLE_TOUCH) then :apple_touch
+        elsif tokens.include?('icon') then :icon
+        end
+      end
+
+      sig { params(page: Page).returns(Icon) }
+      def favicon(page)
+        url = T.must(UrlResolver.resolve('/favicon.ico', page.url))
+        Icon.new(url: url, source: :link_tag, format: :ico)
+      end
+    end
+  end
+end