ucode 0.1.0

data/lib/ucode/audit/extractors/opentype_layout.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "fontisan"
+
+module Ucode
+  module Audit
+    module Extractors
+      # OpenType layout summary: union of GSUB + GPOS scripts and features,
+      # plus a per-script breakdown preserving which feature belongs to
+      # which script under which table.
+      #
+      # Returned fields:
+      #   opentype_layout: Models::Audit::OpenTypeLayout, or nil for
+      #                    Type 1
+      #
+      # Owned here (MECE split from Aggregations, which is UCD-only).
+      class OpenTypeLayout < Base
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          font = context.font
+          return { opentype_layout: nil } unless sfnt?(font)
+
+          gsub_scripts = scripts_in(font, "GSUB")
+          gpos_scripts = scripts_in(font, "GPOS")
+          all_scripts = (gsub_scripts + gpos_scripts).uniq.sort
+
+          by_script = all_scripts.map do |tag|
+            Models::Audit::ScriptFeatures.new(
+              script: tag,
+              gsub_features: features_for(font, "GSUB", tag),
+              gpos_features: features_for(font, "GPOS", tag),
+            )
+          end
+
+          { opentype_layout: Models::Audit::OpenTypeLayout.new(
+            scripts: all_scripts,
+            features: aggregate_features(by_script),
+            by_script: by_script,
+            has_gsub: font.has_table?("GSUB"),
+            has_gpos: font.has_table?("GPOS"),
+          ) }
+        end
+
+        private
+
+        def sfnt?(font)
+          font.is_a?(Fontisan::SfntFont)
+        end
+
+        def scripts_in(font, tag)
+          return [] unless font.has_table?(tag)
+
+          font.table(tag).scripts
+        end
+
+        def features_for(font, tag, script)
+          return [] unless font.has_table?(tag)
+
+          font.table(tag).features(script_tag: script).sort
+        end
+
+        def aggregate_features(by_script)
+          gsub = by_script.flat_map(&:gsub_features)
+          gpos = by_script.flat_map(&:gpos_features)
+          (gsub + gpos).uniq.sort
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/extractors/provenance.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Ucode
+  module Audit
+    module Extractors
+      # Provenance fields: who generated this report, when, from what.
+      #
+      # Returned fields:
+      #   generated_at, ucode_version, source_file, source_sha256,
+      #   source_format, font_index, num_fonts_in_source
+      #
+      # ucode delta vs fontisan: `fontisan_version` is renamed to
+      # `ucode_version` and reads from `Ucode::VERSION`.
+      class Provenance < Base
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          {
+            generated_at: Time.now.utc.iso8601,
+            ucode_version: Ucode::VERSION,
+            source_file: File.expand_path(context.font_path),
+            source_sha256: Digest::SHA256.file(context.font_path).hexdigest,
+            source_format: context.source_format,
+            font_index: context.font_index,
+            num_fonts_in_source: context.num_fonts_in_source,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/extractors/style.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Audit
+    module Extractors
+      # Style fields: weight, width, italic/bold flags, Panose family
+      # classification.
+      #
+      # Returned fields:
+      #   weight_class, width_class, italic, bold, panose
+      #
+      # ucode delta vs fontisan: the standalone `StyleExtractor` class is
+      # NOT ported. The OS/2 + head interpretation rules live inline here.
+      #
+      # MECE: this extractor owns OS/2 + head. fvar-derived fields (axes,
+      # named instances, variable presence) live on the VariationDetail
+      # extractor (TODO 09).
+      #
+      # Boundary: uses only `font.has_table?(tag)` and `font.table(tag)`.
+      # No class-specific branching — any SFNT-compatible font works.
+      class Style < Base
+        FS_SELECTION_ITALIC_BIT = 0
+        MAC_STYLE_BOLD_BIT      = 0
+        private_constant :FS_SELECTION_ITALIC_BIT, :MAC_STYLE_BOLD_BIT
+
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          font = context.font
+          {
+            weight_class: weight_class(font),
+            width_class: width_class(font),
+            italic: italic(font),
+            bold: bold(font),
+            panose: panose(font),
+          }
+        end
+
+        private
+
+        def weight_class(font)
+          os2(font)&.us_weight_class&.to_i
+        end
+
+        def width_class(font)
+          os2(font)&.us_width_class&.to_i
+        end
+
+        # OS/2.fsSelection bit 0 (ITALIC).
+        def italic(font)
+          table = os2(font)
+          return nil if table.nil?
+
+          (table.fs_selection.to_i & (1 << FS_SELECTION_ITALIC_BIT)).nonzero?
+        end
+
+        # head.macStyle bit 0 (BOLD). Per OpenType convention, bold is
+        # read from head, not OS/2.
+        def bold(font)
+          table = head(font)
+          return nil if table.nil?
+
+          (table.mac_style.to_i & (1 << MAC_STYLE_BOLD_BIT)).nonzero?
+        end
+
+        # OS/2.panose as a space-joined 10-digit string,
+        # e.g. "2 0 5 3 0 0 0 0 0 0". nil when no OS/2 table.
+        def panose(font)
+          bytes = os2(font)&.panose
+          return nil if bytes.nil?
+
+          bytes = bytes.to_a
+          return nil if bytes.empty?
+
+          bytes.join(" ")
+        end
+
+        def os2(font)
+          font.has_table?("OS/2") ? font.table("OS/2") : nil
+        end
+
+        def head(font)
+          font.has_table?("head") ? font.table("head") : nil
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/extractors/variation_detail.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "fontisan"
+
+module Ucode
+  module Audit
+    module Extractors
+      # Variable-font detail: fvar axes + named instances + presence flags
+      # for every variation side-table (avar, cvar, HVAR, VVAR, MVAR, gvar).
+      #
+      # Returned fields:
+      #   variation: Models::Audit::VariationDetail, or nil for non-variable
+      #              faces and Type 1 fonts
+      #
+      # A face is considered variable iff the fvar table is present. CFF2
+      # outlines without fvar are not "variable" by this definition (they
+      # may carry variation data but no user-facing axes).
+      class VariationDetail < Base
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          font = context.font
+          return { variation: nil } unless variable?(font)
+
+          fvar = font.table("fvar")
+          return { variation: nil } unless fvar
+
+          name_table = font.has_table?("name") ? font.table("name") : nil
+          axis_tags = axis_tags_from(fvar)
+
+          { variation: Models::Audit::VariationDetail.new(
+            axes: build_axes(name_table, fvar),
+            named_instances: build_instances(name_table, fvar, axis_tags),
+            has_avar: font.has_table?("avar"),
+            has_cvar: font.has_table?("cvar"),
+            has_hvar: font.has_table?("HVAR"),
+            has_vvar: font.has_table?("VVAR"),
+            has_mvar: font.has_table?("MVAR"),
+            has_gvar: font.has_table?("gvar"),
+          ) }
+        end
+
+        private
+
+        def variable?(font)
+          font.is_a?(Fontisan::SfntFont) && font.has_table?("fvar")
+        end
+
+        def build_axes(name_table, fvar)
+          return [] unless fvar.axes
+
+          fvar.axes.map do |axis|
+            Models::Audit::AuditAxis.new(
+              tag: axis.axis_tag,
+              min_value: axis.min_value,
+              default_value: axis.default_value,
+              max_value: axis.max_value,
+              name: english_name(name_table, axis.axis_name_id),
+            )
+          end
+        end
+
+        def build_instances(name_table, fvar, axis_tags)
+          instances = fvar.instances
+          return [] unless instances
+
+          instances.map do |instance|
+            build_instance(name_table, instance, axis_tags)
+          end
+        end
+
+        def build_instance(name_table, instance, axis_tags)
+          subfamily_name = english_name(name_table, instance[:name_id])
+          ps_name_id = instance[:postscript_name_id]
+          ps_name = ps_name_id ? english_name(name_table, ps_name_id) : nil
+          coords = Models::Audit::NamedInstance.format_coordinates(
+            axis_tags, instance[:coordinates]
+          )
+
+          Models::Audit::NamedInstance.new(
+            subfamily_name: subfamily_name,
+            postscript_name: ps_name,
+            coordinates: coords,
+          )
+        end
+
+        def english_name(name_table, name_id)
+          return nil unless name_table && name_id
+
+          name_table.english_name(name_id)
+        end
+
+        def axis_tags_from(fvar)
+          return [] unless fvar.axes
+
+          fvar.axes.map(&:axis_tag)
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/extractors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Autoload hub for the Ucode::Audit::Extractors namespace.
+#
+# Each extractor is a small MECE class with a single `#extract(context)`
+# method returning a hash of AuditReport fields. The Audit::Registry
+# declares the ordered list.
+module Ucode
+  module Audit
+    module Extractors
+      # Cheap extractors (TODO 08) — brief-mode eligible.
+      autoload :Base,       "ucode/audit/extractors/base"
+      autoload :Provenance, "ucode/audit/extractors/provenance"
+      autoload :Identity,   "ucode/audit/extractors/identity"
+      autoload :Style,      "ucode/audit/extractors/style"
+      autoload :Licensing,  "ucode/audit/extractors/licensing"
+      autoload :Coverage,   "ucode/audit/extractors/coverage"
+
+      # Expensive extractors (TODO 09) — full-mode only.
+      autoload :Metrics,           "ucode/audit/extractors/metrics"
+      autoload :Hinting,           "ucode/audit/extractors/hinting"
+      autoload :ColorCapabilities, "ucode/audit/extractors/color_capabilities"
+      autoload :VariationDetail,   "ucode/audit/extractors/variation_detail"
+      autoload :OpenTypeLayout,    "ucode/audit/extractors/opentype_layout"
+
+      # Aggregations (TODO 10) — full-mode only. Driven by ucode's own
+      # UCD baseline, so it depends on baseline resolution succeeding.
+      autoload :Aggregations, "ucode/audit/extractors/aggregations"
+    end
+  end
+end

data/lib/ucode/audit/plane_aggregator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Audit
+    # Rolls up {Models::Audit::BlockSummary}[] into one
+    # {Models::Audit::PlaneSummary} per Unicode plane.
+    #
+    # Pure transformation: input is BlockSummary[], output is
+    # PlaneSummary[] sorted by plane number. No I/O, no Database
+    # access — the per-block work is already done.
+    class PlaneAggregator
+      # @param block_summaries [Array<Models::Audit::BlockSummary>]
+      # @return [Array<Models::Audit::PlaneSummary>] sorted by plane
+      def call(block_summaries)
+        block_summaries.group_by(&:plane).map do |plane, blocks|
+          assigned = blocks.sum(&:total_assigned)
+          covered = blocks.sum(&:covered_count)
+          Models::Audit::PlaneSummary.new(
+            plane: plane,
+            blocks_total: blocks.size,
+            assigned_total: assigned,
+            covered_total: covered,
+            coverage_percent: percent(covered, assigned),
+          )
+        end.sort_by(&:plane)
+      end
+
+      private
+
+      def percent(covered, total)
+        return 0.0 if total.zero?
+
+        (covered.to_f / total * 100).round(2)
+      end
+    end
+  end
+end

data/lib/ucode/audit/registry.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Audit
+    # Ordered list of extractor classes run for every audit face.
+    #
+    # Order matters only for human-readable output (text formatter).
+    # All extractors are independent; their outputs are merged into
+    # one big hash before constructing the AuditReport.
+    #
+    # MECE / OCP: a new concern = one file under
+    # `Ucode::Audit::Extractors::*` + one line in the appropriate list
+    # below. AuditCommand never enumerates extractors directly.
+    module Registry
+      # Full audit: every concern. The five cheap extractors come from
+      # TODO 08; the five expensive extractors come from TODO 09. The
+      # Aggregations extractor (TODO 10) sits last because it depends
+      # on UCD baseline resolution.
+      ORDERED_EXTRACTORS = [
+        Extractors::Provenance,
+        Extractors::Identity,
+        Extractors::Style,
+        Extractors::Licensing,
+        Extractors::Coverage,
+        Extractors::Metrics,
+        Extractors::Hinting,
+        Extractors::ColorCapabilities,
+        Extractors::VariationDetail,
+        Extractors::OpenTypeLayout,
+        Extractors::Aggregations,
+      ].freeze
+
+      # Brief audit: cheap, name-table-only extractors. Used by
+      # `ucode audit --brief` for a fast inventory pass. Stable list —
+      # the expensive extractors are never part of brief mode.
+      BRIEF_EXTRACTORS = [
+        Extractors::Provenance,
+        Extractors::Identity,
+        Extractors::Style,
+        Extractors::Licensing,
+        Extractors::Coverage,
+      ].freeze
+
+      # Iterate the extractors appropriate for the given mode.
+      #
+      # @param mode [Symbol] :full (default) or :brief
+      # @yieldparam extractor_class [Class]
+      # @return [void]
+      def self.each(mode: :full, &)
+        extractors_for(mode).each(&)
+      end
+
+      # @param mode [Symbol] :full or :brief
+      # @return [Array<Class>] the extractor list for the given mode
+      def self.extractors_for(mode)
+        case mode
+        when :brief then BRIEF_EXTRACTORS
+        else ORDERED_EXTRACTORS
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/script_aggregator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Audit
+    # Produces one {Models::Audit::ScriptSummary} per touched Unicode
+    # script for a font's cmap codepoint set, compared against a ucode
+    # UCD baseline.
+    #
+    # Pure transformation: takes the resolved baseline Database + the
+    # font's codepoint list, returns ScriptSummary[].
+    #
+    # v1 scope: uses the Scripts.txt primary-script lookup (one ISO
+    # 15924 code per codepoint). ScriptExtensions — where a single
+    # codepoint contributes to multiple scripts (e.g. punctuation used
+    # across Latn, Grek, Cyrl) — requires a Database schema bump and
+    # is intentionally deferred.
+    class ScriptAggregator
+      # @param database [Ucode::Database, nil]
+      def initialize(database)
+        @database = database
+      end
+
+      # @param codepoints [Enumerable<Integer>]
+      # @return [Array<Models::Audit::ScriptSummary>] sorted by script_code
+      def call(codepoints)
+        return [] if @database.nil? || codepoints.empty?
+
+        grouped = group_by_script(codepoints)
+        grouped.map { |code, covered| build_summary(code, covered) }
+          .sort_by(&:script_code)
+      end
+
+      private
+
+      def group_by_script(codepoints)
+        codepoints.each_with_object(Hash.new { |h, k| h[k] = [] }) do |cp, acc|
+          code = @database.lookup_script(cp)
+          acc[code] << cp if code
+        end
+      end
+
+      def build_summary(script_code, covered_cps)
+        ranges = @database.script_ranges_by_name(script_code)
+        assigned_set = expand_assigned(ranges)
+        covered_set = covered_cps.to_set & assigned_set
+        Models::Audit::ScriptSummary.new(
+          script_code: script_code,
+          script_name: script_name_for(script_code),
+          blocks_total: count_distinct_blocks(ranges),
+          assigned_total: assigned_set.size,
+          covered_total: covered_set.size,
+          coverage_percent: percent(covered_set.size, assigned_set.size),
+          status: Models::Audit::ScriptSummary.derive_status(
+            covered_total: covered_set.size,
+            assigned_total: assigned_set.size,
+          ),
+        )
+      end
+
+      def expand_assigned(ranges)
+        ranges.each_with_object(Set.new) do |r, acc|
+          (r.first_cp..r.last_cp).each { |cp| acc << cp }
+        end
+      end
+
+      # Distinct block names that any of this script's ranges overlaps.
+      # "How many Unicode blocks contain codepoints of this script?"
+      def count_distinct_blocks(ranges)
+        names = Set.new
+        ranges.each do |r|
+          @database.each_block_overlapping(r.first_cp, r.last_cp)
+            .each { |e| names << e.name }
+        end
+        names.size
+      end
+
+      def script_name_for(code)
+        # The Database stores ISO 15924 codes (Latn, Grek, ...). The
+        # long-form name lives in PropertyValueAliases.txt; the audit
+        # does not need it for v1 — code is canonical and consumers
+        # can resolve the long form downstream.
+        code
+      end
+
+      def percent(covered, total)
+        return 0.0 if total.zero?
+
+        (covered.to_f / total * 100).round(2)
+      end
+    end
+  end
+end

data/lib/ucode/audit.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Autoload hub for the Ucode::Audit namespace.
+#
+# The audit pipeline takes a font face (or a library of faces) and
+# produces a structured {Models::Audit::AuditReport} per face, plus a
+# {Models::Audit::LibrarySummary} for directory-level rollups. The
+# pipeline is:
+#
+#   CLI → AuditCommand → Context → Registry.each { |extractor| ... }
+#                                      → merge hashes → AuditReport
+#
+# MECE: every concern (provenance, identity, style, licensing, coverage,
+# aggregations, etc.) lives in exactly one Extractor. Adding a concern =
+# one file under Extractors/ + one line in Registry.
+module Ucode
+  module Audit
+    autoload :Context, "ucode/audit/context"
+    autoload :Registry, "ucode/audit/registry"
+    autoload :Extractors, "ucode/audit/extractors"
+    autoload :CodepointRangeCoalescer, "ucode/audit/codepoint_range_coalescer"
+    autoload :BlockAggregator, "ucode/audit/block_aggregator"
+    autoload :ScriptAggregator, "ucode/audit/script_aggregator"
+    autoload :PlaneAggregator, "ucode/audit/plane_aggregator"
+    autoload :DiscrepancyDetector, "ucode/audit/discrepancy_detector"
+  end
+end

data/lib/ucode/cache.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ucode
+  # On-disk cache layout for fetched UCD sources and derived indices.
+  #
+  # Pure filesystem module. No network access, no parsing. Reads
+  # Ucode.configuration.cache_root for the root path so tests can swap
+  # roots without touching ENV.
+  #
+  # Layout per version:
+  #
+  #   <root>/<version>/
+  #     ucd/              # extracted UCD.zip
+  #     unihan/           # extracted Unihan.zip
+  #     pdfs/             # per-block PDFs
+  #     index/            # blocks.yml, scripts.yml (YAML bsearch index)
+  #     sqlite/           # ucode.sqlite3 (primary lookup)
+  module Cache
+    UCD_DIR = "ucd"
+    UNIHAN_DIR = "unihan"
+    PDFS_DIR = "pdfs"
+    INDEX_DIR = "index"
+    SQLITE_DIR = "sqlite"
+    SQLITE_FILENAME = "ucode.sqlite3"
+    BLOCKS_INDEX_FILENAME = "blocks.yml"
+    SCRIPTS_INDEX_FILENAME = "scripts.yml"
+
+    private_constant :UCD_DIR, :UNIHAN_DIR, :PDFS_DIR, :INDEX_DIR,
+                     :SQLITE_DIR, :SQLITE_FILENAME,
+                     :BLOCKS_INDEX_FILENAME, :SCRIPTS_INDEX_FILENAME
+
+    class << self
+      # @return [Pathname]
+      def root
+        Ucode.configuration.cache_root
+      end
+
+      # @param version [String] e.g. "17.0.0"
+      # @return [Pathname]
+      def version_dir(version)
+        root.join(version)
+      end
+
+      def ucd_dir(version)
+        version_dir(version).join(UCD_DIR)
+      end
+
+      def unihan_dir(version)
+        version_dir(version).join(UNIHAN_DIR)
+      end
+
+      def pdfs_dir(version)
+        version_dir(version).join(PDFS_DIR)
+      end
+
+      def index_dir(version)
+        version_dir(version).join(INDEX_DIR)
+      end
+
+      def sqlite_dir(version)
+        version_dir(version).join(SQLITE_DIR)
+      end
+
+      def sqlite_path(version)
+        sqlite_dir(version).join(SQLITE_FILENAME)
+      end
+
+      def blocks_index_path(version)
+        index_dir(version).join(BLOCKS_INDEX_FILENAME)
+      end
+
+      def scripts_index_path(version)
+        index_dir(version).join(SCRIPTS_INDEX_FILENAME)
+      end
+
+      # True if any extracted content exists for `version`.
+      # @param version [String]
+      # @return [Boolean]
+      def cached?(version)
+        version_dir(version).directory?
+      end
+
+      # All versions present in the cache, sorted ascending.
+      # @return [Array<String>]
+      def cached_versions
+        return [] unless root.directory?
+
+        root.children.select(&:directory?).map { |p| p.basename.to_s }.sort
+      end
+
+      # Idempotent: create the per-version subdirectory tree.
+      # @param version [String]
+      # @return [void]
+      def ensure_version_dir!(version)
+        ucd_dir(version).mkpath
+        unihan_dir(version).mkpath
+        pdfs_dir(version).mkpath
+        index_dir(version).mkpath
+        sqlite_dir(version).mkpath
+      end
+
+      # Remove a version from the cache. No-op if absent.
+      # @param version [String]
+      # @return [void]
+      def remove_version(version)
+        dir = version_dir(version)
+        dir.rmtree if dir.exist?
+      end
+    end
+  end
+end