ucode 0.1.0

data/lib/ucode/index_builder.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "ucode/index"
+require "ucode/range_entry"
+
+module Ucode
+  # Streaming accumulator that turns a sequence of CodePoint records
+  # into per-property sorted + coalesced Index instances.
+  #
+  # Lifecycle:
+  #
+  #   builder = IndexBuilder.new
+  #   Coordinator.new.each_codepoint(...) { |cp| builder.add(cp) }
+  #   builder.blocks_index   # => Index
+  #   builder.scripts_index  # => Index
+  #
+  # The Coordinator yields cps in ascending cp order, so the per-name
+  # cp arrays are already sorted. The final pass coalesces adjacent
+  # cps (gap of 1) into RangeEntry runs.
+  #
+  # **Coalescing caveat**: ranges are derived from ASSIGNED cps only.
+  # If a block has unassigned cps in the middle, the resulting range
+  # will fragment around them. For lookup_block(cp) on an assigned cp,
+  # the answer is correct. For an unassigned cp, the lookup returns
+  # nil. This is a deliberate trade-off for streaming memory bounds —
+  # the canonical block ranges are in `Coordinator#indices.blocks`,
+  # not in the streamed cps.
+  class IndexBuilder
+    def initialize
+      @cps_by_block = Hash.new { |h, k| h[k] = [] }
+      @cps_by_script = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Fold one CodePoint into the per-property accumulators. No-ops if
+    # the cp has no block_id / script_code (e.g. an unassigned cp
+    # surfaced through UnicodeData, or a cp outside any fixture range).
+    # @param cp [Ucode::Models::CodePoint]
+    # @return [void]
+    def add(cp)
+      push_named(@cps_by_block, cp.block_id, cp.cp)
+      push_named(@cps_by_script, cp.script_code, cp.cp)
+    end
+
+    # @return [Index]
+    def blocks_index
+      Index.new(to_entries(@cps_by_block))
+    end
+
+    # @return [Index]
+    def scripts_index
+      Index.new(to_entries(@cps_by_script))
+    end
+
+    private
+
+    def push_named(target, name, cp)
+      return if name.nil? || name.empty?
+
+      target[name] << cp
+    end
+
+    # Flatten {name => [cp, cp, ...]} into Array<RangeEntry>, sorted
+    # by first_cp. Within each name, adjacent cps (gap == 1) coalesce.
+    def to_entries(cps_by_name)
+      cps_by_name.flat_map do |name, cps|
+        coalesce(cps).map { |first, last| RangeEntry.new(first, last, name) }
+      end
+    end
+
+    # Coalesces a sorted cp list into [first, last] runs. cps already
+    # arrive sorted (Coordinator yields in ascending cp order), but
+    # we sort defensively in case the stream was reordered.
+    def coalesce(cps)
+      return [] if cps.empty?
+
+      sorted = cps.sort
+      runs = []
+      first = sorted[0]
+      last = sorted[0]
+
+      sorted[1..].each do |cp|
+        if cp == last + 1
+          last = cp
+        else
+          runs << [first, last]
+          first = cp
+          last = cp
+        end
+      end
+      runs << [first, last]
+      runs
+    end
+  end
+end

data/lib/ucode/models/audit/audit_axis.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # One fvar axis descriptor on an {AuditReport}.
+      #
+      # `min_value` / `default_value` / `max_value` are used (rather than
+      # `min` / `default` / `max`) to avoid colliding with Ruby's built-in
+      # `default` method on classes.
+      class AuditAxis < Lutaml::Model::Serializable
+        attribute :tag, :string
+        attribute :min_value, :float
+        attribute :default_value, :float
+        attribute :max_value, :float
+        attribute :name, :string
+
+        key_value do
+          map "tag",           to: :tag
+          map "min_value",     to: :min_value
+          map "default_value", to: :default_value
+          map "max_value",     to: :max_value
+          map "name",          to: :name
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/audit/audit_diff.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # Structural diff between two {AuditReport}s.
+      #
+      # `left_source`/`right_source` are the original source_file paths
+      # (or report paths) so a consumer reading the diff alone can locate
+      # the inputs.
+      #
+      # `field_changes` lists scalar fields whose values changed.
+      # `codepoints` is the cmap delta ({CodepointSetDiff}).
+      # The remaining fields are array set-diffs over the report's
+      # structural inventory: OpenType features, scripts, UCD blocks.
+      # Each is split into `added_*` (in right, not left) and
+      # `removed_*` (in left, not right).
+      #
+      # ucode delta vs fontisan: drops `added_languages` / `removed_languages`
+      # (CLDR is out of scope).
+      class AuditDiff < Lutaml::Model::Serializable
+        attribute :left_source,      :string
+        attribute :right_source,     :string
+        attribute :field_changes,    FieldChange, collection: true, default: -> { [] }
+        attribute :codepoints,       CodepointSetDiff
+        attribute :added_features,   :string, collection: true, default: -> { [] }
+        attribute :removed_features, :string, collection: true, default: -> { [] }
+        attribute :added_scripts,    :string, collection: true, default: -> { [] }
+        attribute :removed_scripts,  :string, collection: true, default: -> { [] }
+        attribute :added_blocks,     :string, collection: true, default: -> { [] }
+        attribute :removed_blocks,   :string, collection: true, default: -> { [] }
+
+        key_value do
+          map "left_source",      to: :left_source
+          map "right_source",     to: :right_source
+          map "field_changes",    to: :field_changes
+          map "codepoints",       to: :codepoints
+          map "added_features",   to: :added_features
+          map "removed_features", to: :removed_features
+          map "added_scripts",    to: :added_scripts
+          map "removed_scripts",  to: :removed_scripts
+          map "added_blocks",     to: :added_blocks
+          map "removed_blocks",   to: :removed_blocks
+        end
+
+        # True when nothing differs. Useful for the text formatter.
+        #
+        # @return [Boolean]
+        def empty?
+          added_codepoints.zero? && removed_codepoints.zero? &&
+            all_collections_empty?(
+              field_changes,
+              added_features, removed_features,
+              added_scripts, removed_scripts,
+              added_blocks, removed_blocks
+            )
+        end
+
+        def added_codepoints
+          codepoints&.added_count || 0
+        end
+
+        def removed_codepoints
+          codepoints&.removed_count || 0
+        end
+
+        private
+
+        def all_collections_empty?(*collections)
+          collections.all? { |c| c.nil? || c.empty? }
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/audit/audit_report.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # Complete font audit report for a single face.
+      #
+      # Self-describing: one face per file. Carries source provenance
+      # (`source_file`, `source_sha256`, `font_index`, `num_fonts_in_source`)
+      # so a consumer reading a single face report knows whether the
+      # source was a standalone font or a collection face, and can locate
+      # siblings via the source hash.
+      #
+      # The model is passive — no font-parsing logic lives here. The
+      # AuditCommand + Extractors populate every field.
+      #
+      # ucode deltas vs fontisan's AuditReport:
+      #
+      # - Drops CLDR (`cldr_version`, `language_coverage`).
+      # - Renames `fontisan_version` → `ucode_version`.
+      # - Replaces `ucd_version: String` with `baseline: Baseline` (richer
+      #   provenance + pairs with the resolved UCD database).
+      # - Replaces `unicode_scripts: String[]` with `scripts: ScriptSummary[]`
+      #   (structured per-script coverage).
+      # - Replaces `blocks: AuditBlock` with `blocks: BlockSummary` (richer
+      #   per-block status + plane tagging).
+      # - Adds `plane_summaries` (per-plane rollup).
+      # - Adds `discrepancies` (cheap audit signals).
+      class AuditReport < Lutaml::Model::Serializable
+        # --- Provenance ---
+        attribute :generated_at,   :string
+        attribute :ucode_version,  :string
+        attribute :source_file,    :string
+        attribute :source_sha256,  :string
+        attribute :source_format,  :string
+
+        # --- Source layout ---
+        attribute :font_index, :integer
+        attribute :num_fonts_in_source, :integer
+
+        # --- Identity (name table) ---
+        attribute :family_name,      :string
+        attribute :subfamily_name,   :string
+        attribute :full_name,        :string
+        attribute :postscript_name,  :string
+        attribute :version,          :string
+        attribute :font_revision,    :float
+
+        # --- Style (OS/2 + head) ---
+        attribute :weight_class, :integer
+        attribute :width_class,  :integer
+        attribute :italic, Lutaml::Model::Type::Boolean
+        attribute :bold,   Lutaml::Model::Type::Boolean
+        attribute :panose, :string
+
+        # --- Coverage ---
+        attribute :total_codepoints, :integer
+        attribute :total_glyphs,     :integer
+        attribute :cmap_subtables,   :integer, collection: true, default: -> { [] }
+        attribute :codepoint_ranges, CodepointRange, collection: true, default: -> { [] }
+        attribute :codepoints,       :string,        collection: true, default: -> { [] }
+        # --- Aggregations (driven by ucode's own UCD, not ucd.all.flat.zip) ---
+        attribute :baseline, Baseline
+        attribute :blocks,   BlockSummary,   collection: true, default: -> { [] }
+        attribute :scripts,  ScriptSummary,  collection: true, default: -> { [] }
+        attribute :plane_summaries, PlaneSummary, collection: true, default: -> { [] }
+
+        # --- Optional deep tables (nil for Type 1) ---
+        attribute :licensing,           Licensing
+        attribute :metrics,             Metrics
+        attribute :hinting,             Hinting
+        attribute :color_capabilities,  ColorCapabilities
+        attribute :variation,           VariationDetail
+        attribute :opentype_layout,     OpenTypeLayout
+
+        # --- Audit signals ---
+        attribute :discrepancies, Discrepancy, collection: true, default: -> { [] }
+        attribute :warning,       :string
+
+        key_value do
+          # Provenance
+          map "generated_at",       to: :generated_at
+          map "ucode_version",      to: :ucode_version
+          map "source_file",        to: :source_file
+          map "source_sha256",      to: :source_sha256
+          map "source_format",      to: :source_format
+
+          # Source layout
+          map "font_index",          to: :font_index
+          map "num_fonts_in_source", to: :num_fonts_in_source
+
+          # Identity
+          map "family_name",     to: :family_name
+          map "subfamily_name",  to: :subfamily_name
+          map "full_name",       to: :full_name
+          map "postscript_name", to: :postscript_name
+          map "version",         to: :version
+          map "font_revision",   to: :font_revision
+
+          # Style
+          map "weight_class", to: :weight_class
+          map "width_class",  to: :width_class
+          map "italic",       to: :italic
+          map "bold",         to: :bold
+          map "panose",       to: :panose
+
+          # Coverage
+          map "total_codepoints", to: :total_codepoints
+          map "total_glyphs",     to: :total_glyphs
+          map "cmap_subtables",   to: :cmap_subtables
+          map "codepoint_ranges", to: :codepoint_ranges
+          map "codepoints",       to: :codepoints
+
+          # Aggregations
+          map "baseline",         to: :baseline
+          map "blocks",           to: :blocks
+          map "scripts",          to: :scripts
+          map "plane_summaries",  to: :plane_summaries
+
+          # Deep tables
+          map "licensing",          to: :licensing
+          map "metrics",            to: :metrics
+          map "hinting",            to: :hinting
+          map "color_capabilities", to: :color_capabilities
+          map "variation",          to: :variation
+          map "opentype_layout",    to: :opentype_layout
+
+          # Audit signals
+          map "discrepancies", to: :discrepancies
+          map "warning",       to: :warning
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/audit/baseline.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # Metadata about the UCD baseline that an {AuditReport} was
+      # compared against.
+      #
+      # Replaces fontisan's bare `ucd_version: String` field. Carries
+      # enough provenance that a consumer reading the report knows which
+      # UCD build, which ucode/fontisan versions produced the baseline,
+      # and when.
+      class Baseline < Lutaml::Model::Serializable
+        attribute :unicode_version, :string
+        attribute :ucode_version, :string
+        attribute :fontisan_version, :string
+        attribute :source, :string
+        attribute :generated_at, :string
+
+        key_value do
+          map "unicode_version",  to: :unicode_version
+          map "ucode_version",    to: :ucode_version
+          map "fontisan_version", to: :fontisan_version
+          map "source",           to: :source
+          map "generated_at",     to: :generated_at
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/audit/block_summary.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # One Unicode block coverage row on an {AuditReport}.
+      #
+      # Replaces fontisan's `AuditBlock`. Carries per-block coverage
+      # computed against ucode's own UCD baseline (not the legacy
+      # ucd.all.flat.zip), plus an explicit `status` enum so consumers
+      # can filter/sort without recomputing from raw counts.
+      class BlockSummary < Lutaml::Model::Serializable
+        STATUS_COMPLETE = "COMPLETE"
+        STATUS_PARTIAL = "PARTIAL"
+        STATUS_UNCOVERED_ASSIGNED = "UNCOVERED_ASSIGNED"
+        STATUS_NO_ASSIGNED_IN_BLOCK = "NO_ASSIGNED_IN_BLOCK"
+        STATUS_OUTSIDE_BASELINE = "OUTSIDE_BASELINE"
+
+        attribute :name, :string
+        attribute :first_cp, :integer
+        attribute :last_cp, :integer
+        attribute :range, :string
+        attribute :plane, :integer
+        attribute :total_assigned, :integer
+        attribute :covered_count, :integer
+        attribute :missing_count, :integer
+        attribute :coverage_percent, :float
+        attribute :status, :string
+        attribute :missing_codepoints, :integer, collection: true, default: -> { [] }
+        attribute :covered_codepoints, :integer, collection: true, default: -> { [] }
+
+        key_value do
+          map "name",               to: :name
+          map "first_cp",           to: :first_cp
+          map "last_cp",            to: :last_cp
+          map "range",              to: :range
+          map "plane",              to: :plane
+          map "total_assigned",     to: :total_assigned
+          map "covered_count",      to: :covered_count
+          map "missing_count",      to: :missing_count
+          map "coverage_percent",   to: :coverage_percent
+          map "status",             to: :status
+          map "missing_codepoints", to: :missing_codepoints
+          map "covered_codepoints", to: :covered_codepoints
+        end
+
+        # Derive the canonical status string for a block given its
+        # counts. Centralized so the Aggregations extractor and any
+        # downstream consumer compute identically.
+        #
+        # @param covered_count [Integer]
+        # @param total_assigned [Integer]
+        # @param in_baseline [Boolean] false if the block exists in the
+        #   font's cmap but not in the resolved baseline (e.g. PUA blocks
+        #   or a newer Unicode version than ucode knows about).
+        # @return [String] one of the STATUS_* constants
+        def self.derive_status(covered_count:, total_assigned:, in_baseline: true)
+          return STATUS_OUTSIDE_BASELINE unless in_baseline
+          return STATUS_NO_ASSIGNED_IN_BLOCK if total_assigned.zero?
+
+          case covered_count
+          when total_assigned then STATUS_COMPLETE
+          when 0 then STATUS_UNCOVERED_ASSIGNED
+          else STATUS_PARTIAL
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/audit/codepoint_detail.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # Per-codepoint detail row, emitted only in `--verbose` mode.
+      #
+      # Lives in a separate `codepoints.json` file under the directory
+      # emitter (TODO 13) so the main `audit.json` stays compact. Each
+      # row pairs UCD metadata (name, gc, script, age) with the font's
+      # glyph id and (optionally) a relative path to the rendered SVG.
+      class CodepointDetail < Lutaml::Model::Serializable
+        attribute :codepoint, :integer
+        attribute :name, :string
+        attribute :general_category, :string
+        attribute :script, :string
+        attribute :script_extensions, :string, collection: true, default: -> { [] }
+        attribute :block_name, :string
+        attribute :age, :string
+        attribute :glyph_id, :integer
+        attribute :glyph_svg_path, :string
+
+        key_value do
+          map "codepoint",         to: :codepoint
+          map "name",              to: :name
+          map "general_category",  to: :general_category
+          map "script",            to: :script
+          map "script_extensions", to: :script_extensions
+          map "block_name",        to: :block_name
+          map "age",               to: :age
+          map "glyph_id",          to: :glyph_id
+          map "glyph_svg_path",    to: :glyph_svg_path
+        end
+
+        # "U+XXXX" form for human display. Not serialized.
+        # @return [String]
+        def cp_id
+          format("U+%04X", codepoint)
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/audit/codepoint_range.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # A contiguous run of covered codepoints.
+      #
+      # `first_cp`/`last_cp` are inclusive integer endpoints. A single-codepoint
+      # "range" has first_cp == last_cp and renders as `U+XXXX` (no dash).
+      #
+      # Produced by the cmap coverage coalescer from the font's cmap. The
+      # range view replaces a flat per-codepoint list — a 60k-codepoint CJK
+      # font produces tens of ranges rather than 60k strings.
+      class CodepointRange < Lutaml::Model::Serializable
+        attribute :first_cp, :integer
+        attribute :last_cp, :integer
+
+        key_value do
+          map "first_cp", to: :first_cp
+          map "last_cp",  to: :last_cp
+        end
+
+        # Human-readable form: `U+XXXX` for single codepoints,
+        # `U+XXXX-U+XXXX` for true ranges.
+        #
+        # @return [String]
+        def to_s
+          if first_cp == last_cp
+            format("U+%04<cp>X", cp: first_cp)
+          else
+            format("U+%04<first>X-U+%04<last>X", first: first_cp, last: last_cp)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/audit/codepoint_set_diff.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # Diff between two cmap codepoint sets.
+      #
+      # `added`/`removed` are compact range lists ({CodepointRange}) so a
+      # large delta (e.g. CJK extension added) renders as a handful of
+      # ranges rather than thousands of codepoints.
+      #
+      # `unchanged_count` is the intersection size — useful as a sanity
+      # check that the two reports share enough coverage to be meaningfully
+      # comparable.
+      class CodepointSetDiff < Lutaml::Model::Serializable
+        attribute :added,           CodepointRange, collection: true, default: -> { [] }
+        attribute :removed,         CodepointRange, collection: true, default: -> { [] }
+        attribute :added_count,     :integer
+        attribute :removed_count,   :integer
+        attribute :unchanged_count, :integer
+
+        key_value do
+          map "added",           to: :added
+          map "removed",         to: :removed
+          map "added_count",     to: :added_count
+          map "removed_count",   to: :removed_count
+          map "unchanged_count", to: :unchanged_count
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/audit/color_capabilities.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # Color-font capability summary for one face.
+      #
+      # Answers: is this a color font, and if so, which format(s)?
+      # Modern color font formats are mutually exclusive in design but a
+      # single face can carry more than one (e.g. NotoColorEmoji ships
+      # COLR + CBDT + SVG so legacy and modern stacks all render).
+      #
+      # `color_formats` is derived at extraction time so consumers read a
+      # flat string list instead of re-deriving from the boolean lattice.
+      # Empty array ⇒ no color support.
+      class ColorCapabilities < Lutaml::Model::Serializable
+        FORMAT_COLR_V0 = "colr_v0"
+        FORMAT_COLR_V1 = "colr_v1"
+        FORMAT_CPAL    = "cpal"
+        FORMAT_SVG     = "svg"
+        FORMAT_CBDT    = "cbdt"
+        FORMAT_SBIX    = "sbix"
+
+        # COLR (vector color glyphs).
+        attribute :has_colr,             Lutaml::Model::Type::Boolean
+        attribute :colr_version,         :integer
+        attribute :colr_base_glyph_count, :integer
+        attribute :colr_layer_count, :integer
+
+        # CPAL (color palette).
+        attribute :has_cpal,           Lutaml::Model::Type::Boolean
+        attribute :cpal_palette_count, :integer
+        attribute :cpal_color_count,   :integer
+
+        # SVG-in-OpenType.
+        attribute :has_svg, Lutaml::Model::Type::Boolean
+        attribute :svg_document_count, :integer
+
+        # CBDT/CBLC (color bitmaps — paired tables).
+        attribute :has_cbdt,         Lutaml::Model::Type::Boolean
+        attribute :has_cblc,         Lutaml::Model::Type::Boolean
+        # Strike count comes from the paired CBLC locator table.
+        attribute :cbdt_strike_count, :integer
+
+        # sbix (Apple color bitmaps).
+        attribute :has_sbix, Lutaml::Model::Type::Boolean
+        attribute :sbix_strike_count, :integer
+
+        # Derived: ordered list of active color format tags.
+        attribute :color_formats, :string, collection: true, default: -> { [] }
+
+        key_value do
+          map "has_colr",              to: :has_colr
+          map "colr_version",          to: :colr_version
+          map "colr_base_glyph_count", to: :colr_base_glyph_count
+          map "colr_layer_count",      to: :colr_layer_count
+          map "has_cpal",              to: :has_cpal
+          map "cpal_palette_count",    to: :cpal_palette_count
+          map "cpal_color_count",      to: :cpal_color_count
+          map "has_svg",               to: :has_svg
+          map "svg_document_count",    to: :svg_document_count
+          map "has_cbdt",              to: :has_cbdt
+          map "has_cblc",              to: :has_cblc
+          map "cbdt_strike_count",     to: :cbdt_strike_count
+          map "has_sbix",              to: :has_sbix
+          map "sbix_strike_count",     to: :sbix_strike_count
+          map "color_formats",         to: :color_formats
+        end
+
+        # Derive the canonical color_formats list from individual flags.
+        # COLR v1 takes precedence over v0 — a v1 table can serve both.
+        #
+        # @return [Array<String>]
+        def self.derive_formats(has_colr:, colr_version:, has_cpal:,
+                                has_svg:, has_cbdt:, has_sbix:)
+          [].tap do |arr|
+            if has_colr
+              arr << (colr_version == 1 ? FORMAT_COLR_V1 : FORMAT_COLR_V0)
+            end
+            arr << FORMAT_CPAL if has_cpal
+            arr << FORMAT_SVG  if has_svg
+            arr << FORMAT_CBDT if has_cbdt
+            arr << FORMAT_SBIX if has_sbix
+          end
+        end
+      end
+    end
+  end
+end