ucode 0.1.0 → 0.1.1

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    module Audit
+      # Universal-set reference section of a {ReleaseManifest}.
+      #
+      # Records whether the release tree carries a co-located universal
+      # glyph set (TODO 24) and where to find it. fontist.org consumes
+      # this to decide whether to render missing-codepoint thumbnails
+      # from the universal set or fall back to text-only chips.
+      #
+      # When `available` is false, `reason` carries a short diagnostic
+      # string ("universal-set directory not found at <path>"). The
+      # other fields are nil.
+      class ReleaseUniversalSet < Lutaml::Model::Serializable
+        attribute :available, Lutaml::Model::Type::Boolean
+        attribute :manifest_path, :string
+        attribute :glyphs_dir, :string
+        attribute :unicode_version, :string
+        attribute :totals, :hash, default: -> { {} }
+        attribute :reason, :string
+
+        key_value do
+          map "available",       to: :available
+          map "manifest_path",   to: :manifest_path
+          map "glyphs_dir",      to: :glyphs_dir
+          map "unicode_version", to: :unicode_version
+          map "totals",          to: :totals
+          map "reason",          to: :reason
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/audit.rb

@@ -23,6 +23,7 @@ module Ucode
       autoload :PlaneSummary, "ucode/models/audit/plane_summary"
       autoload :Discrepancy, "ucode/models/audit/discrepancy"
       autoload :CodepointDetail, "ucode/models/audit/codepoint_detail"
+      autoload :CodepointProvenance, "ucode/models/audit/codepoint_provenance"
 
       # Ported from fontisan (namespace swap + minor renames)
       autoload :AuditReport, "ucode/models/audit/audit_report"
@@ -45,6 +46,14 @@ module Ucode
       autoload :DuplicateGroup, "ucode/models/audit/duplicate_group"
       autoload :LibrarySummary, "ucode/models/audit/library_summary"
       autoload :AuditDiff, "ucode/models/audit/audit_diff"
+
+      # Release-tree models (TODO 27) — fontist.org-consumable
+      # artifact manifest. ReleaseManifest is the top-level shape;
+      # the others are nested entries.
+      autoload :ReleaseManifest,     "ucode/models/audit/release_manifest"
+      autoload :ReleaseFormulaEntry, "ucode/models/audit/release_formula"
+      autoload :ReleaseFaceEntry,    "ucode/models/audit/release_face"
+      autoload :ReleaseUniversalSet, "ucode/models/audit/release_universal_set"
     end
   end
 end

data/lib/ucode/models/block.rb

@@ -13,6 +13,7 @@ module Ucode
       attribute :range_first, :integer
       attribute :range_last, :integer
       attribute :plane_number, :integer
+      attribute :age, :string
       attribute :codepoint_ids, :string, collection: true, default: -> { [] }
 
       key_value do
@@ -21,6 +22,7 @@ module Ucode
         map "range_first", to: :range_first
         map "range_last", to: :range_last
         map "plane_number", to: :plane_number
+        map "age", to: :age
         map "codepoint_ids", to: :codepoint_ids
       end
 

data/lib/ucode/models/build_report.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    # Build report for one canonical Unicode dataset run. The
+    # deliverable spec'd in TODO 21: emitted at the end of a Mode 1
+    # build as `output/build-report.json`, summarizing what got built,
+    # how (per-tier), per-block, and any failures.
+    #
+    # The model is passive — accumulation logic lives in
+    # {Ucode::Repo::BuildReportAccumulator}; this class only describes
+    # the wire shape and handles (de)serialization via lutaml-model.
+    #
+    # Wire format (see TODO 21):
+    #
+    #   {
+    #     "unicode_version": "17.0.0",
+    #     "ucode_version": "0.2.0",
+    #     "generated_at": "2026-07-01T12:00:00Z",
+    #     "totals": { "assigned": 150012, "built": 150012,
+    #                 "skipped": 0, "failed": 0 },
+    #     "by_tier": { "tier-1": 150012, "pillar-1": 3000, ... },
+    #     "by_block": [
+    #       { "name": "Basic Latin", "assigned": 128, "built": 128,
+    #         "tier_breakdown": { "tier-1": 128 } },
+    #       ...
+    #     ],
+    #     "failures": []
+    #   }
+    #
+    # `by_tier` counts overlap across tiers (a codepoint attempted via
+    # Tier 1 but falling through to Pillar 1 is counted in both);
+    # `built` per-codepoint is the tier that actually produced its
+    # glyph.
+    class BuildReport < Lutaml::Model::Serializable
+      # Total counts for the run.
+      class Totals < Lutaml::Model::Serializable
+        attribute :assigned, :integer, default: 0
+        attribute :built, :integer, default: 0
+        attribute :skipped, :integer, default: 0
+        attribute :failed, :integer, default: 0
+
+        key_value do
+          map "assigned", to: :assigned
+          map "built", to: :built
+          map "skipped", to: :skipped
+          map "failed", to: :failed
+        end
+      end
+
+      # Per-block rollup. One entry per Unicode block in the run.
+      class BlockSummary < Lutaml::Model::Serializable
+        attribute :name, :string
+        attribute :assigned, :integer, default: 0
+        attribute :built, :integer, default: 0
+        attribute :tier_breakdown, :hash, default: -> { {} }
+
+        key_value do
+          map "name", to: :name
+          map "assigned", to: :assigned
+          map "built", to: :built
+          map "tier_breakdown", to: :tier_breakdown
+        end
+      end
+
+      # One failure record. `codepoint` is the integer codepoint (or
+      # nil if the failure is structural); `tier` is the resolver tier
+      # that raised (or nil); `error_class` and `message` carry the
+      # exception details; `backtrace` is optional.
+      class Failure < Lutaml::Model::Serializable
+        attribute :codepoint, :integer
+        attribute :block_name, :string
+        attribute :tier, :string
+        attribute :error_class, :string
+        attribute :message, :string
+        attribute :backtrace, :string, collection: true, default: -> { [] }
+
+        key_value do
+          map "codepoint", to: :codepoint
+          map "block_name", to: :block_name
+          map "tier", to: :tier
+          map "error_class", to: :error_class
+          map "message", to: :message
+          map "backtrace", to: :backtrace
+        end
+      end
+
+      attribute :unicode_version, :string
+      attribute :ucode_version, :string
+      attribute :generated_at, :string
+      attribute :totals, Totals
+      attribute :by_tier, :hash, default: -> { {} }
+      attribute :by_block, BlockSummary, collection: true, default: -> { [] }
+      attribute :failures, Failure, collection: true, default: -> { [] }
+
+      key_value do
+        map "unicode_version", to: :unicode_version
+        map "ucode_version", to: :ucode_version
+        map "generated_at", to: :generated_at
+        map "totals", to: :totals
+        map "by_tier", to: :by_tier
+        map "by_block", to: :by_block
+        map "failures", to: :failures
+      end
+    end
+  end
+end

data/lib/ucode/models/codepoint/glyph.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    class CodePoint < Lutaml::Model::Serializable
+      # Glyph bundle for one codepoint. Records where the SVG lives on
+      # disk and which resolver tier produced it.
+      #
+      # The `svg_path` is relative to the codepoint's own directory
+      # (always "glyph.svg" — the layout is fixed in {Ucode::Repo::Paths}).
+      # The `source` bundle carries the resolver tier name and
+      # provenance string, so the dataset is debuggable end-to-end:
+      # every glyph in the build can be traced back to its origin
+      # (real font, embedded ToUnicode, correlator, or Last Resort).
+      class Glyph < Lutaml::Model::Serializable
+        # Provenance bundle for a glyph — which tier of the 4-tier
+        # resolver produced it. The Ruby class name `Source` mirrors
+        # the wire field name; it is unrelated to the
+        # {Ucode::Glyphs::Source} abstract base.
+        class Source < Lutaml::Model::Serializable
+          attribute :tier, :string
+          attribute :provenance, :string
+
+          key_value do
+            map "tier", to: :tier
+            map "provenance", to: :provenance
+          end
+        end
+
+        attribute :svg_path, :string, default: -> { "glyph.svg" }
+        attribute :source, Source
+
+        key_value do
+          map "svg_path", to: :svg_path
+          map "source", to: :source
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/codepoint.rb

@@ -26,6 +26,7 @@ module Ucode
       autoload :Emoji, "ucode/models/codepoint/emoji"
       autoload :Identifier, "ucode/models/codepoint/identifier"
       autoload :Normalization, "ucode/models/codepoint/normalization"
+      autoload :Glyph, "ucode/models/codepoint/glyph"
 
       # Identity + scalar attributes
       attribute :cp, :integer
@@ -74,6 +75,7 @@ module Ucode
                 collection: true, default: -> { [] }
       attribute :unihan, "Ucode::Models::UnihanEntry"
       attribute :names_list, "Ucode::Models::NamesListEntry"
+      attribute :glyph, Glyph
 
       key_value do
         map "codepoint", to: :cp
@@ -116,6 +118,7 @@ module Ucode
         map "standardized_variants", to: :standardized_variants
         map "unihan", to: :unihan
         map "names_list", to: :names_list
+        map "glyph", to: :glyph
       end
     end
   end

data/lib/ucode/models/glyph_source.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    # One Tier 1 font entry inside a {GlyphSourceMap}. Corresponds to
+    # one `- kind: …` item under a block's `sources:` list in
+    # `config/unicode17_universal_glyph_set.yml`.
+    #
+    # This is the typed representation of a font curation choice. The
+    # {Ucode::Glyphs::Sources::Tier1RealFont} source consumes it to
+    # resolve and load the font; the resolver treats each entry as an
+    # independent tier-1 attempt.
+    #
+    # Wire shape (YAML / JSON identical):
+    #
+    #   kind: fontist          # one of: fontist, path, system
+    #   label: noto-sans       # human + provenance key
+    #   priority: 1            # lower wins; resolver tries in order
+    #   license: OFL           # optional; OFL / PROPRIETARY / etc.
+    #   provenance: "Google Noto Sans"   # optional citation
+    #   path: "/abs/font.ttf"  # required when kind == :path
+    #
+    # `kind` is stored as a plain string on the wire (lutaml-model has
+    # no Symbol adapter for key_value); the {#kind_sym} reader casts it
+    # for internal dispatch.
+    class GlyphSource < Lutaml::Model::Serializable
+      KIND_FONTIST = "fontist"
+      KIND_PATH = "path"
+      KIND_SYSTEM = "system"
+      KINDS = [KIND_FONTIST, KIND_PATH, KIND_SYSTEM].freeze
+      private_constant :KIND_FONTIST, :KIND_PATH, :KIND_SYSTEM, :KINDS
+
+      attribute :kind, :string
+      attribute :label, :string
+      attribute :priority, :integer, default: -> { 100 }
+      attribute :license, :string
+      attribute :provenance, :string
+      attribute :path, :string
+
+      key_value do
+        map "kind", to: :kind
+        map "label", to: :label
+        map "priority", to: :priority
+        map "license", to: :license
+        map "provenance", to: :provenance
+        map "path", to: :path
+      end
+
+      # @return [Symbol] :fontist, :path, :system; raises if kind is
+      #   blank — every entry must declare its kind.
+      def kind_sym
+        raise ArgumentError, "GlyphSource#kind is required" if kind.nil? || kind.empty?
+
+        kind.to_sym
+      end
+
+      # @return [Boolean] true when this entry requires a `path` field
+      #   (kind == :path). Used by the loader to validate structure.
+      def requires_path?
+        kind_sym == :path
+      end
+
+      # Renders this source as the legacy font-spec string consumed by
+      # {Ucode::Glyphs::RealFonts::FontLocator}: `label=/path/to/font`
+      # for kind=path, or `label` (the fontist formula name) for
+      # kind=fontist. The locator's `locate` understands both shapes.
+      #
+      # This is the one adapter method that lets the typed model
+      # integrate with the existing locator without rewriting it.
+      #
+      # @return [String]
+      def to_font_spec
+        case kind_sym
+        when :path
+          raise ArgumentError, "GlyphSource#{label} has kind=path but no path" if path.nil? || path.empty?
+
+          "#{label}=#{path}"
+        when :fontist, :system
+          label
+        end
+      end
+    end
+  end
+end

data/lib/ucode/models/glyph_source_map.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+require "ucode/models/glyph_source"
+
+module Ucode
+  module Models
+    # Top-level shape of `config/unicode17_universal_glyph_set.yml`.
+    # Pairs envelope metadata (Unicode + ucode version, generated_at)
+    # with the block→sources map itself.
+    #
+    # Block keys are the verbatim Unicode block name with runs of
+    # whitespace collapsed to a single underscore — the canonical
+    # block id used everywhere else in this codebase (see
+    # {Ucode::Parsers::Blocks}): "Basic_Latin", "Greek_and_Coptic",
+    # "CJK_Unified_Ideographs_Extension_J". Never slugified beyond
+    # whitespace collapsing.
+    #
+    # Wire shape (note: `map:` is a hash keyed by block id, not an
+    # array):
+    #
+    #   unicode_version: "17.0.0"
+    #   ucode_version: "0.2.0"
+    #   generated_at: "2026-06-28T00:00:00Z"
+    #   default_sources:                 # applies when a block's sources are absent/empty
+    #     - kind: fontist
+    #       label: noto-sans
+    #       priority: 1
+    #       license: OFL
+    #   map:
+    #     Basic_Latin:
+    #       sources:
+    #         - kind: fontist
+    #           label: noto-sans
+    #           priority: 1
+    #     Sidetic:
+    #       sources: []
+    #
+    # An entry with `sources: []` (or omitted) is valid: it declares
+    # "no block-specific Tier 1 font; fall back to `default_sources`,
+    # then to Pillars 1-3". The fallback chain is implemented in
+    # {#sources_for}; the raw map is left untouched.
+    #
+    # The hash is stored as a raw `:hash` attribute (lutaml-model
+    # collection semantics don't pair cleanly with a hash-keyed wire
+    # shape); the typed accessors wrap each entry's raw hashes in
+    # {GlyphSource} instances on demand.
+    class GlyphSourceMap < Lutaml::Model::Serializable
+      attribute :unicode_version, :string
+      attribute :ucode_version, :string
+      attribute :generated_at, :string
+      attribute :default_sources_raw, :hash, collection: true, default: -> { [] }
+      attribute :block_sources, :hash, default: -> { {} }
+
+      key_value do
+        map "unicode_version", to: :unicode_version
+        map "ucode_version", to: :ucode_version
+        map "generated_at", to: :generated_at
+        map "default_sources", to: :default_sources_raw
+        map "map", to: :block_sources
+      end
+
+      # @param block_id [String] verbatim block id (underscore form)
+      # @return [Array<GlyphSource>] sources for the block, in
+      #   priority order (ascending). Falls through block-specific →
+      #   `default_sources` → empty.
+      def sources_for(block_id)
+        raw = block_sources[block_id]
+        list = extract_sources_list(raw)
+        list = default_sources_list if list.empty?
+        list.map { |h| GlyphSource.from_hash(h.transform_keys(&:to_s)) }
+          .sort_by(&:priority)
+      end
+
+      # @return [Array<GlyphSource>] the top-level default sources,
+      #   typed and priority-sorted. Empty when not declared.
+      def default_sources
+        default_sources_list
+          .map { |h| GlyphSource.from_hash(h.transform_keys(&:to_s)) }
+          .sort_by(&:priority)
+      end
+
+      # @param block_id [String]
+      # @return [Boolean] true if the block has any entry in the map
+      #   (even with empty sources). Does not consider `default_sources`.
+      def has_block?(block_id)
+        block_sources.key?(block_id)
+      end
+
+      # @return [Array<String>] every block_id that appears in the map
+      #   (regardless of whether it has sources).
+      def block_ids
+        block_sources.keys
+      end
+
+      # @return [Array<String>] block_ids whose own `sources:` list has
+      #   at least one entry. Blocks relying on `default_sources` are
+      #   excluded — they have no block-specific policy.
+      def configured_block_ids
+        block_sources.each_with_object([]) do |(block_id, raw), acc|
+          acc << block_id if any_sources?(raw)
+        end
+      end
+
+      private
+
+      # Each block's value in the YAML is either:
+      #   - `{sources: [...]}` (canonical form), or
+      #   - `[...]` (shorthand: the sources list directly).
+      # Return the sources array in both cases; empty for `nil`.
+      def extract_sources_list(raw)
+        return [] if raw.nil?
+        return raw if raw.is_a?(Array)
+        return Array(raw["sources"]) if raw.is_a?(Hash) && raw.key?("sources")
+        return Array(raw[:sources]) if raw.is_a?(Hash) && raw.key?(:sources)
+
+        []
+      end
+
+      # Each block's value in the YAML is either `{sources: [...]}` or
+      # directly an array (shorthand). Normalize to the array of
+      # source-hashes form.
+      def any_sources?(raw)
+        return false if raw.nil?
+        return raw.any? if raw.is_a?(Array)
+
+        raw.is_a?(Hash) && Array(raw["sources"] || raw[:sources]).any?
+      end
+
+      # `default_sources` on the wire is a list of source hashes. Older
+      # configs may omit it; treat absence as an empty list.
+      def default_sources_list
+        Array(default_sources_raw)
+      end
+    end
+  end
+end

data/lib/ucode/models/specialist_font.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ucode
+  module Models
+    # One entry in `config/specialist_fonts.yml` — a Tier 1 font that
+    # fontist's formula index does not carry (academic sites, SIL
+    # downloads, GitHub releases). The fetcher walks a list of these
+    # and materializes each `path` on disk.
+    #
+    # Wire shape (YAML):
+    #
+    #   label: Lentariso
+    #   version: "1.033"
+    #   license: OFL
+    #   url: "https://github.com/.../Lentariso.otf"
+    #   sha256: "<hex>"          # null until first successful fetch
+    #   path: "data/fonts/Lentariso.otf"
+    #   extract: false
+    #   extract_member: null     # required when extract: true
+    #   provenance: "Imperial Aramaic / Phoenician / Sidetic coverage"
+    #
+    # `url: null` marks a local-only entry: the user supplies the
+    # file at `path` (which may use `~` and shell globs); the fetcher
+    # never attempts a network download for these.
+    class SpecialistFont < Lutaml::Model::Serializable
+      LICENSE_OFL = "OFL"
+      private_constant :LICENSE_OFL
+
+      attribute :label, :string
+      attribute :version, :string
+      attribute :license, :string, default: -> { LICENSE_OFL }
+      attribute :url, :string
+      attribute :sha256, :string
+      attribute :path, :string
+      attribute :extract, :boolean, default: -> { false }
+      attribute :extract_member, :string
+      attribute :provenance, :string
+
+      key_value do
+        map "label", to: :label
+        map "version", to: :version
+        map "license", to: :license
+        map "url", to: :url
+        map "sha256", to: :sha256
+        map "path", to: :path
+        map "extract", to: :extract
+        map "extract_member", to: :extract_member
+        map "provenance", to: :provenance
+      end
+
+      def local_only?
+        url.nil? || url.empty?
+      end
+
+      def ofl?
+        license == LICENSE_OFL
+      end
+
+      def hash_known?
+        !sha256.nil? && !sha256.empty?
+      end
+
+      def extract?
+        extract == true
+      end
+    end
+  end
+end

data/lib/ucode/models/specialist_font_manifest.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+require "ucode/models/specialist_font"
+
+module Ucode
+  module Models
+    # Typed view over `config/specialist_fonts.yml`. Carries the full
+    # list of {SpecialistFont} entries; provides lookup by label so
+    # the fetcher can honor `--label Lentariso` without scanning the
+    # array itself.
+    #
+    # The manifest is pure data — it does not know the path it was
+    # loaded from. Persistence of computed SHA256 hashes back to disk
+    # is the responsibility of {Ucode::Fetch::SpecialistFontFetcher},
+    # which owns the file path and writes atomically after a run.
+    class SpecialistFontManifest < Lutaml::Model::Serializable
+      attribute :fonts, SpecialistFont, collection: true
+
+      key_value do
+        map "fonts", to: :fonts
+      end
+
+      # @param label [String] exact label match
+      # @return [SpecialistFont, nil]
+      def find_by_label(label)
+        fonts.find { |font| font.label == label }
+      end
+
+      # @return [Array<String>] labels of every entry, in declared order
+      def labels
+        fonts.map(&:label)
+      end
+
+      # @param label [String]
+      # @return [SpecialistFontManifest] a new manifest containing only
+      #   the matching font. Returns self unchanged if the label is
+      #   unknown (the fetcher reports it as a separate failure).
+      def only(label)
+        match = find_by_label(label)
+        return self if match.nil?
+
+        self.class.new(fonts: [match])
+      end
+    end
+  end
+end