ucode 0.1.0 → 0.1.1

data/lib/ucode/audit/release.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Audit
+    # Release-tree assembler (TODO 27).
+    #
+    # Composes a fontist.org-consumable release artifact from one or
+    # more per-formula library audits plus the universal-set reference.
+    # The release tree is the unit `fontist.org/scripts/fetch-data.sh`
+    # consumes — a single tarball of `<output_root>/font_audit_release/`
+    # is self-contained.
+    #
+    # Layout (per TODO 27):
+    #
+    #   <output_root>/font_audit_release/
+    #   ├── audit/<formula_slug>/<postscript_name>/...  # per-face audit
+    #   ├── universal_glyph_set/                        # TODO 24 build
+    #   ├── library.json                                # formulas + faces
+    #   └── manifest.json                               # versions + sha256s
+    #
+    # Components:
+    #
+    # - {FormulaAudits} — value object pairing a formula slug with its
+    #   library-wide audit summary.
+    # - {LibraryIndexBuilder} — pure builder for `library.json`.
+    # - {ManifestBuilder} — pure builder for `manifest.json` (returns a
+    #   {Models::Audit::ReleaseManifest}).
+    # - {Emitter} — orchestrator that drives {Emitter::FaceDirectory}
+    #   per formula and writes the two top-level indices.
+    #
+    # The emitter is pure I/O: it consumes ready-built
+    # {Models::Audit::LibrarySummary} instances. Running the audits is
+    # the caller's responsibility (see {Ucode::Commands::ReleaseCommand}).
+    module Release
+      autoload :FormulaAudits,        "ucode/audit/release/formula_audits"
+      autoload :FaceCard,             "ucode/audit/release/face_card"
+      autoload :LibraryIndexBuilder,  "ucode/audit/release/library_index_builder"
+      autoload :ManifestBuilder,      "ucode/audit/release/manifest_builder"
+      autoload :Emitter,              "ucode/audit/release/emitter"
+    end
+  end
+end

data/lib/ucode/audit/ucd_only_reference.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Audit
+    # {CoverageReference} backed by a {Ucode::Database}. The "legacy"
+    # reference: derives the assigned codepoint set from block ranges
+    # alone, with no per-codepoint provenance.
+    #
+    # Used by the audit pipeline when no universal-set manifest is
+    # available (or the user explicitly opts out via
+    # `--reference-universal-set=none`). All audits before TODO 25
+    # behaved this way.
+    class UcdOnlyReference < CoverageReference
+      # @param database [Ucode::Database, nil] when nil, every query
+      #   returns empty / false — caller should surface a warning.
+      def initialize(database:)
+        super()
+        @database = database
+      end
+
+      attr_reader :database
+
+      # @return [Symbol] :ucd
+      def kind
+        :ucd
+      end
+
+      # (see CoverageReference#include?)
+      def include?(codepoint)
+        return false if @database.nil?
+
+        !@database.lookup_block(codepoint).nil?
+      end
+
+      # (see CoverageReference#block_name_for)
+      def block_name_for(codepoint)
+        return nil if @database.nil?
+
+        @database.lookup_block(codepoint)
+      end
+
+      # (see CoverageReference#entries_for_block)
+      def entries_for_block(block_id)
+        return [] if @database.nil?
+
+        ranges = @database.block_ranges_by_name(block_id)
+        return [] if ranges.nil? || ranges.empty?
+
+        ranges.flat_map { |r| expand_range(r) }
+      end
+
+      # (see CoverageReference#reference_id)
+      def reference_id
+        version = @database&.ucd_version || "unknown"
+        "ucd:#{version}"
+      end
+
+      # UCD-only references carry no provenance. Returning nil signals
+      # "do not populate `missing_codepoint_provenance`" so the audit
+      # report preserves the legacy wire shape.
+      #
+      # @return [nil]
+      def provenance_for(_codepoints)
+        nil
+      end
+
+      private
+
+      def expand_range(range)
+        (range.first_cp..range.last_cp).map do |cp|
+          Entry.new(codepoint: cp, id: format_id(cp), tier: nil, source: nil)
+        end
+      end
+
+      def format_id(cp)
+        width = cp <= 0xFFFF ? 4 : 6
+        format("U+%0*X", width, cp)
+      end
+    end
+  end
+end

data/lib/ucode/audit/universal_set_reference.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module Ucode
+  module Audit
+    # {CoverageReference} backed by a universal-set manifest (TODO 24).
+    # Every codepoint in the set carries tier + source provenance, so
+    # a missing-codepoint report can answer "what does the missing
+    # glyph look like, and where did the universal set source it
+    # from?".
+    #
+    # The manifest itself records codepoints but not block
+    # membership, so a {Ucode::Database} is still required to map
+    # block name -> assigned codepoints. The reference answers per
+    # codepoint "is this in the universal set, and what tier/source
+    # did it come from?".
+    class UniversalSetReference < CoverageReference
+      # @param manifest [Ucode::Models::UniversalSetManifest, String, Pathname]
+      #   pre-loaded manifest, or a path to a manifest.json. A path is
+      #   loaded lazily on first query.
+      # @param database [Ucode::Database, nil] used for block lookups.
+      def initialize(manifest:, database:)
+        super()
+        @manifest_source = manifest
+        @database = database
+      end
+
+      # @return [Symbol] :universal_set
+      def kind
+        :universal_set
+      end
+
+      # (see CoverageReference#include?)
+      def include?(codepoint)
+        entries_by_cp.key?(codepoint)
+      end
+
+      # (see CoverageReference#block_name_for)
+      def block_name_for(codepoint)
+        return nil if @database.nil?
+
+        @database.lookup_block(codepoint)
+      end
+
+      # (see CoverageReference#entries_for_block)
+      def entries_for_block(block_id)
+        return [] if @database.nil?
+
+        ranges = @database.block_ranges_by_name(block_id)
+        return [] if ranges.nil? || ranges.empty?
+
+        ranges.flat_map { |r| expand_range(r) }.compact
+      end
+
+      # (see CoverageReference#reference_id)
+      def reference_id
+        sha = manifest.source_config_sha256
+        short_sha = sha ? sha.to_s[0, 12] : "no-sha"
+        "universal-set:#{manifest.unicode_version}:#{short_sha}"
+      end
+
+      # @return [Hash{String=>Object}] provenance metadata for the
+      #   audit report's `baseline` field
+      def baseline_metadata
+        {
+          "unicode_version" => manifest.unicode_version,
+          "ucode_version" => manifest.ucode_version,
+          "source_config_sha256" => manifest.source_config_sha256,
+          "reference_kind" => "universal-set",
+        }
+      end
+
+      # (see CoverageReference#provenance_for)
+      # @return [Array<Hash{Symbol=>Object}>] one hash per codepoint,
+      #   in input order
+      def provenance_for(codepoints)
+        codepoints.map { |cp| row_for(cp) }
+      end
+
+      # The underlying manifest model, loaded lazily from disk.
+      # @return [Ucode::Models::UniversalSetManifest]
+      def manifest
+        @manifest ||= load_manifest
+      end
+
+      # The UCD database used for block lookups. Exposed so the
+      # BlockAggregator can map codepoints -> block names through the
+      # same Database instance the reference was built against.
+      # @return [Ucode::Database, nil]
+      attr_reader :database
+
+      private
+
+      def entries_by_cp
+        @entries_by_cp ||= manifest.entries.to_h { |e| [e.codepoint, e] }
+      end
+
+      def expand_range(range)
+        (range.first_cp..range.last_cp).map do |cp|
+          entry = entries_by_cp[cp]
+          next nil unless entry
+
+          CoverageReference::Entry.new(
+            codepoint: cp, id: entry.id,
+            tier: entry.tier, source: entry.source,
+          )
+        end
+      end
+
+      def row_for(codepoint)
+        entry = entries_by_cp[codepoint]
+        {
+          codepoint: codepoint,
+          tier: entry&.tier,
+          source: entry&.source,
+        }
+      end
+
+      def load_manifest
+        case @manifest_source
+        when Ucode::Models::UniversalSetManifest
+          @manifest_source
+        when String, Pathname
+          hash = JSON.parse(Pathname.new(@manifest_source).read)
+          Ucode::Models::UniversalSetManifest.from_hash(hash)
+        else
+          raise ArgumentError,
+                "manifest must be a UniversalSetManifest or a path, " \
+                "got #{@manifest_source.class}"
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit.rb

@@ -23,5 +23,36 @@ module Ucode
     autoload :ScriptAggregator, "ucode/audit/script_aggregator"
     autoload :PlaneAggregator, "ucode/audit/plane_aggregator"
     autoload :DiscrepancyDetector, "ucode/audit/discrepancy_detector"
+
+    # CoverageReference hierarchy (TODO 25): pluggable baseline that
+    # the audit pipeline compares a font's cmap against. The default
+    # is UCD-only; supply a UniversalSetReference when a universal
+    # glyph set manifest is on disk so per-codepoint provenance is
+    # attached to every missing-codepoint row.
+    autoload :CoverageReference, "ucode/audit/coverage_reference"
+    autoload :UcdOnlyReference, "ucode/audit/ucd_only_reference"
+    autoload :UniversalSetReference, "ucode/audit/universal_set_reference"
+
+    # Per-face orchestrator (TODO 11) — shared by LibraryAuditor and
+    # the future CLI AuditCommand.
+    autoload :FaceAuditor, "ucode/audit/face_auditor"
+
+    # Cross-report orchestration (TODO 11).
+    autoload :Differ, "ucode/audit/differ"
+    autoload :LibraryAuditor, "ucode/audit/library_auditor"
+    autoload :LibraryAggregator, "ucode/audit/library_aggregator"
+
+    # Human-readable text output (TODO 12).
+    autoload :Formatters, "ucode/audit/formatters"
+
+    # Mode 2 directory output writers (TODO 13).
+    autoload :Emitter, "ucode/audit/emitter"
+
+    # Standalone HTML browsers for Mode 2 output (TODOs 14+15).
+    autoload :Browser, "ucode/audit/browser"
+
+    # Release-tree assembler (TODO 27) — fontist.org-consumable
+    # artifact that composes per-formula audits + the universal set.
+    autoload :Release, "ucode/audit/release"
   end
 end