ucode 0.3.2 → 0.4.0

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,90 @@
+# 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
+
+        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

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

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
-require "open3"
 require "pathname"
 
+require "ucode/glyphs/embedded_fonts/mutool"
+
 module Ucode
   module Glyphs
     module EmbeddedFonts
-      # Walks the Code Charts PDF once via `mutool info` + `mutool show`
-      # and builds an Array of {RawFontDescriptor} — one per Type0 font
-      # that has the required descendant CIDFont, FontDescriptor, and
-      # FontFile2/3 + Identity CIDToGIDMap.
-      #
-      # Pure subprocess + parsing concern. Does NOT resolve codepoint →
-      # GID (that's {CodepointMapper}'s job). The descriptor carries
-      # every ref the mapper needs to do its work.
       class PdfIndexer
-        # @param source [PdfLocation]
-        def initialize(source:)
+        Type0Entry = Struct.new(:font_obj_id, :base_font, keyword_init: true)
+
+        # @param source [PdfSource]
+        # @param mutool_info [Mutool::Info] injectable for tests
+        # @param mutool_show [Mutool::Show] injectable for tests
+        def initialize(source:, mutool_info: Mutool::Info.new,
+                       mutool_show: Mutool::Show.new)
           @source = source
+          @mutool_info = mutool_info
+          @mutool_show = mutool_show
         end
 
         # @return [Array<RawFontDescriptor>]
@@ -68,11 +68,45 @@ module Ucode
         # @param base_font [String] e.g. "GPJAHB+WolofGaraySansSerif"
         # @return [Boolean] true if this font appears on any page
         def font_appears?(base_font)
-          font_entries_cache.key?(base_font)
+          type0_base_fonts.include?(base_font)
         end
 
         private
 
+        # Single source of truth for the Type0 font list. Both
+        # `discover_type0_fonts` (keyed by obj_id) and
+        # `font_appears?` (membership check by name) derive their
+        # answer from this parse, so changes to `mutool info`'s output
+        # format break in exactly one place.
+        #
+        # @return [Array<Type0Entry>]
+        def type0_entries
+          @type0_entries ||= parse_type0_entries
+        end
+
+        # @return [Set<String>] every Type0 BaseFont name seen
+        def type0_base_fonts
+          @type0_base_fonts ||= type0_entries.each_with_object(Set.new) do |e, s|
+            s << e.base_font
+          end
+        end
+
+        def parse_type0_entries
+          seen = Set.new
+          mutool_info_text.each_line.filter_map do |line|
+            next unless line.include?("Type0")
+
+            m = line.match(/Type0\s+'([^']+)'\s+\S+\s+\((\d+)\s+0\s+R\)/)
+            next unless m
+
+            font_obj_id = m[2].to_i
+            next if seen.include?(font_obj_id)
+
+            seen << font_obj_id
+            Type0Entry.new(font_obj_id: font_obj_id, base_font: m[1])
+          end
+        end
+
         def build_descriptors(type0_refs, type0_dicts, descendant_dicts, fontdesc_dicts)
           type0_refs.filter_map do |font_obj_id, base_font|
             build_descriptor(
@@ -133,35 +167,15 @@ module Ucode
         # ---- mutool subprocess + dict parsing ----------------------------
 
         def discover_type0_fonts
-          text = mutool_info_text
-          result = {}
-          seen = Set.new
-          text.each_line do |line|
-            next unless line.include?("Type0")
-
-            m = line.match(/Type0\s+'([^']+)'\s+\S+\s+\((\d+)\s+0\s+R\)/)
-            next unless m
-
-            font_obj_id = m[2].to_i
-            next if seen.include?(font_obj_id)
-
-            seen << font_obj_id
-            result[font_obj_id] = m[1]
+          type0_entries.to_h do |e|
+            [e.font_obj_id, e.base_font]
           end
-          result
         end
 
         def fetch_objects(obj_ids)
           return {} if obj_ids.empty?
 
-          args = ["mutool", "show", "-g",
-                  @source.pdf_to_s].concat(obj_ids.map(&:to_s))
-          out, err, status = Open3.capture3(*args)
-          unless status.success?
-            raise Ucode::EmbeddedFontsMissingError,
-                  "mutool show failed: #{err.strip}"
-          end
-
+          out = @mutool_show.grep(@source.pdf_to_s, *obj_ids)
           parse_grep_output(out)
         end
 
@@ -208,27 +222,7 @@ module Ucode
         end
 
         def mutool_info_text
-          @mutool_info_text ||= run_mutool_info
-        end
-
-        def run_mutool_info
-          out, err, status = Open3.capture3("mutool", "info", @source.pdf_to_s)
-          status.success? ? out + err : ""
-        end
-
-        def font_entries_cache
-          @font_entries_cache ||= begin
-            result = {}
-            mutool_info_text.each_line do |line|
-              next unless line.include?("Type0")
-
-              font_match = line.match(/Type0\s+'([^']+)'/)
-              next unless font_match
-
-              result[font_match[1]] = true
-            end
-            result
-          end
+          @mutool_info_text ||= @mutool_info.call(@source.pdf_to_s)
         end
       end
     end

data/lib/ucode/glyphs/embedded_fonts/{pdf_location.rb → pdf_source.rb}

@@ -27,7 +27,7 @@ module Ucode
       # the BaseFont (e.g. `CIAIIP+Uni2000Generalpunctuation.ttf`).
       # Re-runs skip extraction when the cached file is newer than the
       # PDF.
-      class PdfLocation
+      class PdfSource
         attr_reader :pdf_path, :cache_dir
 
         # @param pdf [String, Pathname, nil] path to a Code Charts PDF

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

@@ -1,51 +1,35 @@
 # frozen_string_literal: true
 
-require "open3"
 require "pathname"
 
-require "ucode/error"
+require "ucode/glyphs/embedded_fonts/mutool"
+require "ucode/glyphs/embedded_fonts/trace_parser"
 
 module Ucode
   module Glyphs
     module EmbeddedFonts
       # Thin I/O wrapper around `mutool trace <pdf> <page>`.
       #
-      # Runs mutool on the given pages, captures the XML output,
-      # delegates parsing to {TraceParser}, and returns a flat
-      # `Array<TraceGlyph>` across all pages.
-      #
-      # The only class in the trace pipeline that touches the
-      # filesystem / spawns subprocesses. Everything upstream
-      # (parser, correlator) is pure.
+      # Delegates the actual subprocess to {Mutool::Trace} and the
+      # XML parsing to {TraceParser}. Kept for backward compatibility
+      # with callers that pre-date the Mutool seam.
       class TraceRunner
         # @param pdf_path [Pathname, String]
-        def initialize(pdf_path)
+        # @param mutool [Mutool::Trace] injectable for tests
+        def initialize(pdf_path, mutool: Mutool::Trace.new)
           @pdf_path = Pathname.new(pdf_path)
+          @mutool = mutool
         end
 
         # @param page_numbers [Array<Integer>] 1-based PDF page numbers
         # @return [Array<TraceGlyph>]
         def trace(page_numbers)
-          page_numbers.flat_map { |page| trace_page(page) }
-        end
-
-        private
+          return [] if page_numbers.empty?
 
-        def trace_page(page)
-          xml = run_mutool(page)
-          TraceParser.parse(xml)
-        end
-
-        def run_mutool(page)
-          out, err, status = Open3.capture3(
-            "mutool", "trace", @pdf_path.to_s, page.to_s,
-          )
-          unless status.success?
-            raise Ucode::EmbeddedFontsMissingError,
-                  "mutool trace failed: #{(out + err).strip}"
+          page_numbers.flat_map do |page|
+            xml = @mutool.call(@pdf_path, page)
+            TraceParser.parse(xml)
           end
-
-          out + err
         end
       end
     end

data/lib/ucode/glyphs/embedded_fonts.rb

@@ -36,7 +36,7 @@ module Ucode
     # `mutool info` (font enumeration) and `mutool show -b -o` (raw
     # stream extraction).
     module EmbeddedFonts
-      autoload :PdfLocation, "ucode/glyphs/embedded_fonts/pdf_location"
+      autoload :PdfSource, "ucode/glyphs/embedded_fonts/pdf_source"
       autoload :ToUnicode, "ucode/glyphs/embedded_fonts/tounicode"
       autoload :FontEntry, "ucode/glyphs/embedded_fonts/font_entry"
       autoload :RawFontDescriptor, "ucode/glyphs/embedded_fonts/raw_font_descriptor"
@@ -50,6 +50,8 @@ module Ucode
       autoload :TraceParser, "ucode/glyphs/embedded_fonts/trace_parser"
       autoload :TraceCorrelator, "ucode/glyphs/embedded_fonts/trace_correlator"
       autoload :TraceRunner, "ucode/glyphs/embedded_fonts/trace_runner"
+      autoload :Mutool, "ucode/glyphs/embedded_fonts/mutool"
+      autoload :PageTraceCache, "ucode/glyphs/embedded_fonts/page_trace_cache"
       autoload :Svg, "ucode/glyphs/embedded_fonts/svg"
       autoload :Renderer, "ucode/glyphs/embedded_fonts/renderer"
       autoload :Writer, "ucode/glyphs/embedded_fonts/writer"

data/lib/ucode/glyphs/real_fonts/coverage_auditor.rb

@@ -5,10 +5,6 @@ require "time"
 
 require "fontisan"
 
-require_relative "block_coverage"
-require_relative "font_coverage_report"
-require_relative "unicode_17_blocks"
-
 module Ucode
   module Glyphs
     module RealFonts

data/lib/ucode/glyphs/real_fonts/font_coverage_report.rb

@@ -2,8 +2,6 @@
 
 require "lutaml/model"
 
-require_relative "block_coverage"
-
 module Ucode
   module Glyphs
     module RealFonts

data/lib/ucode/glyphs/real_fonts/writer.rb

@@ -3,8 +3,6 @@
 require "fileutils"
 require "pathname"
 
-require_relative "font_coverage_report"
-
 module Ucode
   module Glyphs
     module RealFonts

data/lib/ucode/glyphs/sources/pillar1_embedded_tounicode.rb

@@ -31,7 +31,7 @@ module Ucode
         # @param renderer [EmbeddedFonts::Renderer] the renderer to
         #   delegate to. Callers typically construct it with the
         #   {EmbeddedFonts::Catalog} built from the resolved Code
-        #   Charts {EmbeddedFonts::PdfLocation}. To enable pillar-2
+        #   Charts {EmbeddedFonts::PdfSource}. To enable pillar-2
         #   fallback, that Catalog must be constructed with
         #   +correlator_configs:+.
         def initialize(renderer:)

data/lib/ucode/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ucode
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/ucode.gemspec

@@ -45,12 +45,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "base64"
-  # Pin fontisan to 0.2.22 — 0.2.23+ removed
-  # `Fontisan::Commands::AuditCommand` (used by RealFonts::CoverageAuditor)
-  # and 0.4.x removed the entire Audit subsystem. Until
-  # CoverageAuditor is rewritten against the new fontisan API, this
-  # pin keeps the existing audit path working.
-  spec.add_dependency "fontisan", "= 0.2.22"
+  spec.add_dependency "fontisan", "~> 0.4", ">= 0.4.9"
   spec.add_dependency "fontist", "~> 3.0"
   spec.add_dependency "logger"
   spec.add_dependency "lutaml-model", "~> 0.8"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ucode
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -28,16 +28,22 @@ dependencies:
   name: fontisan
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.22
+        version: 0.4.9
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.22
+        version: 0.4.9
 - !ruby/object:Gem::Dependency
   name: fontist
   requirement: !ruby/object:Gem::Requirement
@@ -156,77 +162,6 @@ files:
 - Gemfile
 - README.md
 - Rakefile
-- TODO.extract-code-chart/01-pdf-fetch-validation.md
-- TODO.extract-code-chart/02-block-name-resolver.md
-- TODO.extract-code-chart/03-codechart-namespace.md
-- TODO.extract-code-chart/04-codechart-extractor.md
-- TODO.extract-code-chart/05-provenance-and-sidecar.md
-- TODO.extract-code-chart/06-codechart-writer.md
-- TODO.extract-code-chart/07-codechart-cli.md
-- TODO.extract-code-chart/08-specs.md
-- TODO.full/00-README.md
-- TODO.full/01-panglyph-vision.md
-- TODO.full/02-panglyph-repo-bootstrap.md
-- TODO.full/03-panglyph-font-builder.md
-- TODO.full/04-panglyph-publish-pipeline.md
-- TODO.full/05-ucode-0-1-1-release.md
-- TODO.full/06-fontisan-remove-audit.md
-- TODO.full/07-fontisan-remove-ucd.md
-- TODO.full/08-archive-private-bin-build.md
-- TODO.full/09-archive-public-structure.md
-- TODO.full/10-fontist-org-woff-glyphs.md
-- TODO.full/11-fontist-org-audit-coverage.md
-- TODO.full/12-implementation-order.md
-- TODO.full/13-fontisan-font-writer-api.md
-- TODO.full/14-fontisan-table-writers.md
-- TODO.full/15-panglyph-builder-real.md
-- TODO.full/16-archive-public-sync-workflows.md
-- TODO.full/17-fontist-org-font-picker.md
-- TODO.full/18-comprehensive-spec-coverage.md
-- TODO.full/19-ucode-0-1-2-patch.md
-- TODO.full/20-fontisan-0-2-23-release.md
-- TODO.new/00-README.md
-- TODO.new/01-pillar-terminology-alignment.md
-- TODO.new/02-audit-schema-design.md
-- TODO.new/03-directory-output-spec.md
-- TODO.new/04-fontist-org-contract.md
-- TODO.new/05-baseline-unicode17-coverage-audit.md
-- TODO.new/06-audit-namespace-skeleton.md
-- TODO.new/07-audit-models-port.md
-- TODO.new/08-extractors-cheap-port.md
-- TODO.new/09-extractors-expensive-port.md
-- TODO.new/10-aggregations-ucd-rewrite.md
-- TODO.new/11-differ-and-library-auditor-port.md
-- TODO.new/12-formatters-port.md
-- TODO.new/13-directory-emitter.md
-- TODO.new/14-html-face-browser.md
-- TODO.new/15-html-library-browser.md
-- TODO.new/16-cli-audit-subcommands.md
-- TODO.new/17-fontisan-cleanup-audit.md
-- TODO.new/18-fontisan-cleanup-ucd.md
-- TODO.new/19-fontisan-docs-update.md
-- TODO.new/20-canonical-resolver-4-tier.md
-- TODO.new/21-canonical-unicode17-build.md
-- TODO.new/22-implementation-order.md
-- TODO.new/23-universal-glyph-set-source-map.md
-- TODO.new/24-universal-glyph-set-build.md
-- TODO.new/25-font-audit-against-universal-set.md
-- TODO.new/26-missing-glyph-reporter.md
-- TODO.new/27-fontist-org-consumer-integration.md
-- TODO.new/28-implementation-order-update.md
-- TODO.new/29-universal-set-curation-uc17.md
-- TODO.new/30-tier1-font-acquisition.md
-- TODO.new/31-universal-set-production-build.md
-- TODO.new/32-uc17-coverage-matrix.md
-- TODO.new/33-specialist-font-acquisition-refresh.md
-- TODO.new/34-pillar2-content-stream-correlator.md
-- TODO.new/35-universal-set-production-run.md
-- TODO.new/36-per-font-coverage-audit.md
-- TODO.new/37-coverage-highlight-reporter.md
-- TODO.new/38-fontist-org-glyph-consumer.md
-- TODO.new/39-implementation-order-update-32-38.md
-- TODO.new/40-archive-private-uses-ucode-audit.md
-- TODO.new/41-ucode-unicode-archive-bridge.md
 - UCODE_CHANGELOG.md
 - config/specialist_fonts.yml
 - config/unicode17_tier1_fonts.yml
@@ -357,10 +292,20 @@ files:
 - lib/ucode/glyphs/embedded_fonts.rb
 - lib/ucode/glyphs/embedded_fonts/catalog.rb
 - lib/ucode/glyphs/embedded_fonts/codepoint_mapper.rb
+- lib/ucode/glyphs/embedded_fonts/codepoint_mapper/correlator_strategy.rb
+- lib/ucode/glyphs/embedded_fonts/codepoint_mapper/strategy.rb
+- lib/ucode/glyphs/embedded_fonts/codepoint_mapper/tounicode_strategy.rb
+- lib/ucode/glyphs/embedded_fonts/codepoint_mapper/trace_strategy.rb
 - lib/ucode/glyphs/embedded_fonts/content_stream_correlator.rb
 - lib/ucode/glyphs/embedded_fonts/font_entry.rb
+- lib/ucode/glyphs/embedded_fonts/mutool.rb
+- lib/ucode/glyphs/embedded_fonts/mutool/draw.rb
+- lib/ucode/glyphs/embedded_fonts/mutool/info.rb
+- lib/ucode/glyphs/embedded_fonts/mutool/show.rb
+- lib/ucode/glyphs/embedded_fonts/mutool/trace.rb
+- lib/ucode/glyphs/embedded_fonts/page_trace_cache.rb
 - lib/ucode/glyphs/embedded_fonts/pdf_indexer.rb
-- lib/ucode/glyphs/embedded_fonts/pdf_location.rb
+- lib/ucode/glyphs/embedded_fonts/pdf_source.rb
 - lib/ucode/glyphs/embedded_fonts/positional_matcher.rb
 - lib/ucode/glyphs/embedded_fonts/raw_font_descriptor.rb
 - lib/ucode/glyphs/embedded_fonts/renderer.rb