ucode 0.3.3 → 0.5.0

data/lib/ucode/glyphs/embedded_fonts/codepoint_mapper.rb

@@ -1,128 +1,188 @@
 # frozen_string_literal: true
 
-require "open3"
-require "pathname"
-require "tempfile"
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/strategy"
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/tounicode_strategy"
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/correlator_strategy"
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/trace_strategy"
+require "ucode/glyphs/embedded_fonts/mutool"
+require "ucode/glyphs/embedded_fonts/page_trace_cache"
+require "ucode/error"
 
 module Ucode
   module Glyphs
     module EmbeddedFonts
-      # Resolves codepoint → GID for one Type0 font via a 3-path strategy:
+      # Resolves codepoint → GID for one Type0 font via a chain of
+      # {Strategy} subclasses.
       #
-      # 1. **ToUnicode CMap** — the font's `/ToUnicode` stream (Tier 1
-      #    for pillar 1). Parsed by {ToUnicode}.
-      # 2. **Caller-supplied correlator config** (pillar 2) — render the
-      #    font's pages to SVG and run {ContentStreamCorrelator}.
-      # 3. **Auto-detect via mutool trace** (pillar 2b) — trace every
-      #    page and run {TraceCorrelator} positionally.
+      # The chain is partitioned by {Strategy#positional?}:
       #
-      # Each path returns a `{codepoint => gid}` map. First non-empty
-      # result wins; the strategy stops there.
+      #   * Intrinsic strategies (ToUnicodeStrategy) read the font's
+      #     own CMap. Tried in chain order; the first non-empty result
+      #     wins.
+      #   * Positional strategies (CorrelatorStrategy, TraceStrategy)
+      #     attribute glyphs by chart-grid geometry. Expensive — they
+      #     shell out to mutool per page — so they only run when an
+      #     intrinsic strategy cannot cover the requested block scope.
       #
-      # Pure strategy orchestration — does NOT parse the PDF object graph
-      # (that's {PdfIndexer}'s job). Takes a {RawFontDescriptor} + the
-      # shared {PdfIndexer} (for page_count + font_appears? queries used
-      # by the trace fallback).
+      # When positional strategies run, their results merge over the
+      # intrinsic result with positional precedence: chart geometry is
+      # authoritative for in-block specimens, while a font's CMap can
+      # be misleading (Enclosed Ideographic Supplement, where the
+      # embedded CJKSymbols font's CMap maps its CIDs to the *composing*
+      # ideographs rather than the squared characters themselves).
+      #
+      # Two escape hatches let callers control the gating:
+      #
+      #   * `block_range:` — when set, an intrinsic result with zero
+      #     in-block intersection is treated as "wrong scope" and
+      #     dropped, so positional strategies can take over. Auto-detect
+      #     for the U1F200 class of failure (Option 1).
+      #   * `force_positional_for_font_ids:` — Type0 font object IDs
+      #     that always go through positional attribution, regardless
+      #     of whether the intrinsic strategy succeeded. Escape hatch
+      #     for partial-overlap cases where the CMap covers some
+      #     in-block codepoints but positional attribution is still
+      #     desired for the rest (Option 2).
+      #
+      # Adding a new strategy = one Strategy subclass + (if positional)
+      # a `positional?` override + one entry in the chain. No edit to
+      # {#map} (Open/Closed Principle).
       class CodepointMapper
-        # @param source [PdfLocation]
-        # @param correlator_configs [Hash{Integer=>ContentStreamCorrelator::Config}]
-        #   caller-supplied pillar-2 configs, keyed by font_obj_id
-        # @param indexer [PdfIndexer] for page_count + font_appears? queries
-        def initialize(source:, correlator_configs:, indexer:)
-          @source = source
-          @correlator_configs = correlator_configs
-          @indexer = indexer
+        # @param strategies [Array<Strategy>] chain; partitioned by
+        #   Strategy#positional? at map time
+        # @param block_range [Range<Integer>, nil] codepoint scope the
+        #   caller is extracting. nil = intrinsic result is always
+        #   trusted (legacy behavior; the caller doesn't know or care
+        #   about block scope).
+        # @param force_positional_for_font_ids [Set<Integer>] Type0
+        #   font object IDs that always trigger positional attribution
+        def initialize(strategies:, block_range: nil,
+                       force_positional_for_font_ids: Set.new)
+          @strategies = strategies
+          @block_range = block_range
+          @force_positional_for_font_ids = force_positional_for_font_ids
+        end
+
+        # Convenience builder — wires up the default 3-strategy chain
+        # with default Mutool wrappers. Callers that need to inject
+        # stubs for tests should construct strategies directly and pass
+        # them to +#initialize+.
+        #
+        # @param trace_cache [PageTraceCache, nil] when provided, the
+        #   TraceStrategy shares this cache (lets the caller reuse the
+        #   traced pages for downstream concerns like Catalog's
+        #   location lookup). nil = construct internally.
+        # @return [CodepointMapper]
+        def self.build(source:, correlator_configs:, indexer:,
+                       block_range: nil, force_positional_for_font_ids: Set.new,
+                       mutool_show: Mutool::Show.new,
+                       mutool_draw: Mutool::Draw.new,
+                       mutool_trace: Mutool::Trace.new,
+                       trace_cache: nil)
+          trace_cache ||= PageTraceCache.new(
+            pdf: source.pdf_path,
+            page_count: indexer.page_count,
+            mutool: mutool_trace,
+          )
+          strategies = [
+            ToUnicodeStrategy.new(source: source, mutool_show: mutool_show),
+            CorrelatorStrategy.new(source: source,
+                                   correlator_configs: correlator_configs,
+                                   mutool_draw: mutool_draw),
+            TraceStrategy.new(cache: trace_cache, indexer: indexer),
+          ]
+          new(strategies: strategies,
+              block_range: block_range,
+              force_positional_for_font_ids: force_positional_for_font_ids)
         end
 
         # @param descriptor [RawFontDescriptor]
-        # @return [Hash{Integer=>Integer}] codepoint => gid; empty when
-        #   no strategy produces a map
+        # @return [Hash{Integer=>Integer}] codepoint => gid; empty
+        #   when no strategy produces a mapping
         def map(descriptor)
           return {} unless descriptor.cid_map_kind == :identity
 
-          from_tounicode = map_from_tounicode(descriptor.tounicode_ref)
-          return from_tounicode unless from_tounicode.empty?
-
-          from_correlator = map_from_correlator(descriptor.font_obj_id)
-          return from_correlator unless from_correlator.empty?
+          positional, intrinsic = partition_strategies
+          intrinsic_result = run_intrinsic(descriptor, intrinsic)
+          return intrinsic_result if positional.empty?
+          return intrinsic_result unless needs_positional?(descriptor,
+                                                           intrinsic_result)
 
-          map_from_trace(descriptor.base_font)
+          positional_result = run_positional(descriptor, positional)
+          merge_with_positional_precedence(intrinsic_result, positional_result)
         end
 
         private
 
-        # ---- Strategy 1: /ToUnicode CMap --------------------------------
-
-        def map_from_tounicode(tu_ref)
-          return {} unless tu_ref
-
-          cmap_text = fetch_tounicode(tu_ref)
-          cid_to_cp = ToUnicode.parse(cmap_text)
-          build_codepoint_map(cid_to_cp)
+        # `Enumerable#partition` returns `[truthy_group, falsy_group]`,
+        # so the first element is positional strategies and the second
+        # is intrinsic. Naming them explicitly here avoids the
+        # destructure-order footgun.
+        def partition_strategies
+          positional, intrinsic = @strategies.partition(&:positional?)
+          [positional, intrinsic]
         end
 
-        def build_codepoint_map(cid_to_cp)
-          cid_to_cp.each_with_object({}) do |(cid, cp), h|
-            h[cp] = cid
-          end
-        end
+        # Intrinsic chain: first non-empty result wins. preserves the
+        # pre-partition semantics so the legacy ToUnicode-only flow
+        # behaves identically when no positional strategies exist.
+        def run_intrinsic(descriptor, strategies)
+          strategies.each do |s|
+            next unless s.supports?(descriptor)
 
-        def fetch_tounicode(obj_id)
-          Tempfile.create("ucode-tounicode") do |tmp|
-            tmp.close
-            ok = system("mutool", "show", "-o", tmp.path, "-b",
-                        @source.pdf_to_s, obj_id.to_s,
-                        out: File::NULL, err: File::NULL)
-            unless ok
-              raise Ucode::EmbeddedFontsMissingError,
-                    "mutool show failed for ToUnicode obj=#{obj_id}"
-            end
-
-            File.binread(tmp.path).force_encoding("UTF-8")
+            result = s.map(descriptor)
+            return result unless result.empty?
           end
+          {}
         end
 
-        # ---- Strategy 2: caller-supplied correlator config --------------
+        # Positional strategies are gated behind three conditions, any
+        # of which triggers them:
+        #
+        #   1. Caller explicitly listed this font in
+        #      `force_positional_for_font_ids` (Option 2 escape hatch).
+        #   2. No intrinsic strategy produced a mapping (legacy
+        #      fallback for fonts without ToUnicode).
+        #   3. The intrinsic result fell entirely outside the
+        #      caller's block scope — the font's CMap encoded the
+        #      wrong codepoints (Option 1 auto-detect, e.g. U1F200).
+        def needs_positional?(descriptor, intrinsic_result)
+          return true if @force_positional_for_font_ids.include?(descriptor.font_obj_id)
+          return true if intrinsic_result.empty?
+          return true if intrinsic_out_of_scope?(intrinsic_result)
+
+          false
+        end
 
-        def map_from_correlator(font_obj_id)
-          config = @correlator_configs[font_obj_id]
-          return {} unless config
+        def intrinsic_out_of_scope?(intrinsic_result)
+          return false unless @block_range
 
-          svg = render_pages(config.page_numbers)
-          ContentStreamCorrelator.new(config).correlate(svg)
+          # block_range is a Range, not an Array; Array#intersect? would
+          # force an eager .to_a conversion on potentially huge CJK ranges.
+          intrinsic_result.keys.all? { |cp| !@block_range.include?(cp) }
         end
 
-        def render_pages(page_numbers)
-          return "" if page_numbers.nil? || page_numbers.empty?
+        # Positional chain: union of all positional strategies' results.
+        # Within positional, earlier strategies win on conflict (chain
+        # order expresses caller preference — CorrelatorStrategy
+        # before TraceStrategy when both are configured).
+        def run_positional(descriptor, strategies)
+          merged = {}
+          strategies.each do |s|
+            next unless s.supports?(descriptor)
 
-          out, err, status = Open3.capture3(
-            "mutool", "draw", "-F", "svg",
-            @source.pdf_to_s,
-            *page_numbers.map(&:to_s),
-          )
-          unless status.success?
-            raise Ucode::EmbeddedFontsMissingError,
-                  "mutool draw failed: #{err.strip}"
+            s.map(descriptor).each { |cp, gid| merged[cp] ||= gid }
           end
-
-          out
+          merged
         end
 
-        # ---- Strategy 3: auto-detect via mutool trace --------------------
-
-        def map_from_trace(base_font)
-          return {} unless @indexer.font_appears?(base_font)
-
-          runner = TraceRunner.new(@source.pdf_path)
-          correlator = TraceCorrelator.new(specimen_font_name: base_font)
-
-          (1..@indexer.page_count).each_with_object({}) do |page, mapping|
-            glyphs = runner.trace([page])
-            page_mapping = correlator.correlate(glyphs)
-            page_mapping.each do |cp, gid|
-              mapping[cp] ||= gid
-            end
-          end
+        # Merge intrinsic and positional results. Positional wins on
+        # conflict (chart geometry is authoritative for in-block
+        # specimens).
+        def merge_with_positional_precedence(intrinsic, positional)
+          merged = intrinsic.dup
+          positional.each { |cp, gid| merged[cp] = gid }
+          merged
         end
       end
     end

data/lib/ucode/glyphs/embedded_fonts/mutool/draw.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/glyphs/embedded_fonts/mutool"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      module Mutool
+        class Draw
+          def initialize(runner: SystemRunner.new)
+            @runner = runner
+          end
+
+          def svg(pdf, *pages)
+            return "" if pages.empty?
+
+            @runner.run("mutool", "draw", "-F", "svg", pdf.to_s,
+                        *pages.map(&:to_s))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/mutool/info.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/glyphs/embedded_fonts/mutool"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      module Mutool
+        class Info
+          def initialize(runner: SystemRunner.new)
+            @runner = runner
+          end
+
+          def call(pdf)
+            @runner.run("mutool", "info", pdf.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/mutool/show.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "tempfile"
+
+require "ucode/glyphs/embedded_fonts/mutool"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      module Mutool
+        class Show
+          def initialize(runner: SystemRunner.new)
+            @runner = runner
+          end
+
+          def grep(pdf, *obj_ids)
+            return "" if obj_ids.empty?
+
+            @runner.run("mutool", "show", "-g", pdf.to_s,
+                        *obj_ids.map(&:to_s))
+          end
+
+          def stream(pdf, obj_id)
+            Tempfile.create("mutool-stream") do |tmp|
+              tmp.close
+              @runner.run("mutool", "show", "-o", tmp.path, "-b",
+                          pdf.to_s, obj_id.to_s)
+              File.binread(tmp.path).force_encoding("UTF-8")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/mutool/trace.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/glyphs/embedded_fonts/mutool"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      module Mutool
+        class Trace
+          def initialize(runner: SystemRunner.new)
+            @runner = runner
+          end
+
+          def call(pdf, *pages)
+            return "" if pages.empty?
+
+            @runner.run("mutool", "trace", pdf.to_s,
+                        *pages.map(&:to_s))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/mutool.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "open3"
+
+require "ucode/error"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      module Mutool
+        autoload :Info, "ucode/glyphs/embedded_fonts/mutool/info"
+        autoload :Show, "ucode/glyphs/embedded_fonts/mutool/show"
+        autoload :Draw, "ucode/glyphs/embedded_fonts/mutool/draw"
+        autoload :Trace, "ucode/glyphs/embedded_fonts/mutool/trace"
+
+        class SystemRunner
+          def run(*argv)
+            out, err, status = Open3.capture3(*argv)
+            return out + err if status.success?
+
+            raise Ucode::MutoolError.new(
+              "mutool failed (exit #{status.exitstatus}): #{err.strip}",
+              context: { argv: argv },
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/page_trace_cache.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/glyphs/embedded_fonts/mutool"
+require "ucode/glyphs/embedded_fonts/trace_parser"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Per-PDF trace cache. Runs `mutool trace` once per page
+      # (1..page_count), parses each result, and stores glyphs
+      # grouped by page so each TraceStrategy can correlate
+      # positionally without re-tracing.
+      #
+      # Replaces the O(F × P) explosion in the pre-cache TraceStrategy,
+      # which spawned mutool trace once per page per CID font. For
+      # Code Charts PDFs with F trace-needing fonts and P pages, that
+      # was F×P subprocess invocations; this cache makes it exactly P.
+      #
+      # Why per-page grouping: TraceCorrelator's algorithm clusters
+      # label glyphs by Y bucket, and Y positions are page-local.
+      #
+      # Lazy: glyphs are only fetched when a strategy first asks for
+      # them. PDFs where every font has /ToUnicode never trigger the
+      # trace at all.
+      class PageTraceCache
+        # @param pdf [Pathname, String]
+        # @param page_count [Integer] total pages in the PDF
+        # @param mutool [Mutool::Trace]
+        def initialize(pdf:, page_count:, mutool: Mutool::Trace.new)
+          @pdf = Pathname.new(pdf)
+          @page_count = page_count
+          @mutool = mutool
+        end
+
+        # @return [Array<Array<TraceGlyph>>] one Array per page,
+        #   1-indexed (index 0 is unused). Each inner array holds
+        #   every glyph emitted by `mutool trace` on that page.
+        def glyphs_by_page
+          @glyphs_by_page ||= fetch_glyphs_by_page
+        end
+
+        # @param base_font [String] specimen font BaseFont name
+        # @yieldparam page [Integer] 1-based page number
+        # @yieldparam glyphs [Array<TraceGlyph>] every glyph on that
+        #   page (all fonts — TraceCorrelator filters internally)
+        # @return [Boolean] true if at least one page references the
+        #   font; false otherwise
+        # @return [Enumerator] if no block given
+        def each_page_for(base_font)
+          return enum_for(:each_page_for, base_font) unless block_given?
+
+          present_in_any = false
+          glyphs_by_page.each_with_index do |glyphs, idx|
+            next if idx.zero?
+
+            present = glyphs.any? { |g| g.font_name == base_font }
+            next unless present
+
+            present_in_any = true
+            yield idx, glyphs
+          end
+          present_in_any
+        end
+
+        # @param base_font [String]
+        # @return [Boolean] true if any page references this font
+        def references_font?(base_font)
+          glyphs_by_page.any? do |page_glyphs|
+            page_glyphs.any? { |g| g.font_name == base_font }
+          end
+        end
+
+        # Locate the first occurrence of a specific (font, gid) pair
+        # across all traced pages. Returns nil when no match. Used by
+        # {Catalog#location_for} to attribute a codepoint's source
+        # page + (x, y) without exposing the cache's internal layout
+        # to callers.
+        #
+        # @param base_font [String] specimen font BaseFont name
+        # @param gid [Integer] glyph id inside that font
+        # @return [Hash{Symbol=>Integer, Float}, nil]
+        #   `{ page: Integer, x: Float, y: Float }` or nil
+        def find_glyph(base_font:, gid:)
+          glyphs_by_page.each_with_index do |page_glyphs, idx|
+            next if idx.zero?
+
+            match = page_glyphs.find do |g|
+              g.font_name == base_font && g.gid == gid
+            end
+            return { page: idx, x: match.x, y: match.y } if match
+          end
+          nil
+        end
+
+        private
+
+        def fetch_glyphs_by_page
+          result = [[]] # index 0 unused (1-based pages)
+          return result unless @page_count.positive?
+
+          (1..@page_count).each do |page|
+            xml = @mutool.call(@pdf, page)
+            result << TraceParser.parse(xml)
+          end
+          result
+        end
+      end
+    end
+  end
+end