ucode 0.1.0 → 0.1.1

data/lib/ucode/audit/emitter/face_directory.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/audit/emitter/paths"
+require "ucode/audit/emitter/index_emitter"
+require "ucode/audit/emitter/block_emitter"
+require "ucode/audit/emitter/plane_emitter"
+require "ucode/audit/emitter/script_emitter"
+require "ucode/audit/emitter/codepoint_emitter"
+require "ucode/audit/emitter/glyph_emitter"
+require "ucode/audit/emitter/collection_emitter"
+require "ucode/audit/emitter/library_emitter"
+require "ucode/audit/browser/face_page"
+require "ucode/audit/browser/library_page"
+
+module Ucode
+  module Audit
+    module Emitter
+      # Top-level Mode 2 orchestrator. Walks an AuditReport (or a list
+      # of reports for a collection, or a library summary) and emits the
+      # full directory tree per `03-directory-output-spec.md`.
+      #
+      # Owns the chunk-emitter composition: callers never touch
+      # {IndexEmitter} / {BlockEmitter} / etc. directly. The chunk
+      # emitters themselves stay single-purpose (one chunk kind each)
+      # and take an explicit `face_dir` Pathname — they don't know
+      # whether the face lives at `output/font_audit/<label>/` or under
+      # a collection subdir.
+      #
+      # Three entry points:
+      #
+      #   - {#emit_face}       — one standalone face
+      #   - {#emit_collection} — one TTC source (N sibling faces)
+      #   - {#emit_library}    — directory-mode (M face labels)
+      #
+      # Idempotency is delegated to each chunk emitter via
+      # {Ucode::Repo::AtomicWrites}; re-running the same audit produces
+      # zero writes on the second pass.
+      class FaceDirectory
+        # @param output_root [String, Pathname] top-level output root
+        #   (e.g. "output"). The library root is `<output_root>/font_audit`.
+        # @param verbose [Boolean] emit codepoints/<NAME>.json per block
+        # @param with_glyphs [Boolean] emit glyphs/U+XXXX.svg per covered cp
+        # @param glyph_resolver [Proc(Integer) -> String, nil] SVG source
+        #   for {GlyphEmitter}; defaults to a proc that returns nil
+        #   (no glyphs emitted). Replaced by the canonical 4-tier
+        #   resolver (TODO 20) when ready.
+        # @param database [Ucode::Database, nil] baseline UCD lookup for
+        #   {CodepointEmitter} enrichment
+        # @param emit_browser [Boolean] also write the self-contained
+        #   HTML browsers — `<face_dir>/index.html` per face and
+        #   `<library_root>/index.html` for library mode. Default false.
+        # @param universal_set_root [String, Pathname, nil] root of a
+        #   co-located universal-set build. When present and
+        #   `emit_browser:` is true, the face browser advertises glyph
+        #   paths in its overview JSON so missing-codepoint chips can
+        #   render the universal-set glyph at runtime.
+        # @param with_missing_glyph_pages [Boolean] emit one standalone
+        #   `<face_dir>/missing/<BLOCK>.html` per touched block with
+        #   missing codepoints. Requires `emit_browser:` and a reachable
+        #   `universal_set_root:` (silently no-ops otherwise).
+        def initialize(output_root:, verbose: false, with_glyphs: false,
+                       glyph_resolver: GlyphEmitter::DEFAULT_RESOLVER,
+                       database: nil, emit_browser: false,
+                       universal_set_root: nil, with_missing_glyph_pages: false)
+          @output_root = output_root
+          @verbose = verbose
+          @with_glyphs = with_glyphs
+          @emit_browser = emit_browser
+          @database = database
+          @universal_set_root = universal_set_root
+          @with_missing_glyph_pages = with_missing_glyph_pages
+          @index_emitter = IndexEmitter.new
+          @block_emitter = BlockEmitter.new
+          @plane_emitter = PlaneEmitter.new
+          @script_emitter = ScriptEmitter.new
+          @codepoint_emitter = CodepointEmitter.new
+          @glyph_emitter = GlyphEmitter.new(glyph_resolver: glyph_resolver)
+          @collection_emitter = CollectionEmitter.new
+          @library_emitter = LibraryEmitter.new
+        end
+
+        # @param label [String] sanitized face label (caller-sanitized)
+        # @param report [Models::Audit::AuditReport]
+        # @return [Pathname] the per-face directory written
+        def emit_face(label:, report:)
+          emit_face_at(Paths.face_dir(@output_root, label), report)
+        end
+
+        # @param source_label [String] sanitized collection label
+        # @param reports [Array<Models::Audit::AuditReport>]
+        # @return [Array<String>] per-face subdirectory names
+        def emit_collection(source_label:, reports:)
+          @collection_emitter.emit(@output_root, source_label, reports,
+                                   face_directory: self)
+        end
+
+        # @param summary [Models::Audit::LibrarySummary]
+        # @return [Boolean] true if library index was written
+        def emit_library(summary:)
+          summary.per_face_reports.each do |report|
+            emit_face(label: face_label(report), report: report)
+          end
+          written = @library_emitter.emit(@output_root, summary)
+          emit_library_browser(summary) if @emit_browser
+          written
+        end
+
+        # Hook called by {CollectionEmitter} to write one face under a
+        # collection root. Computes the per-face subdirectory name from
+        # the face_index so the source order is preserved on disk.
+        #
+        # @api private
+        # @param source_label [String]
+        # @param face_index [Integer]
+        # @param report [Models::Audit::AuditReport]
+        # @return [String] the per-face subdirectory name (e.g. "00-Mona")
+        def emit_collection_face(source_label:, face_index:, report:)
+          face_label = format("%<idx>02d-%<label>s",
+                              idx: face_index,
+                              label: sanitize(report.postscript_name))
+          emit_face_at(
+            Paths.collection_face_dir(@output_root, source_label, face_index,
+                                      sanitize(report.postscript_name)),
+            report,
+          )
+          face_label
+        end
+
+        # Write one face's full chunk tree under an explicit face_dir.
+        #
+        # Public entry point for callers that compute their own face_dir
+        # (e.g. {Ucode::Audit::Release::Emitter} builds the release tree
+        # at `<release_root>/audit/<slug>/<face>/`). Callers that want
+        # the default library-mode layout should use {#emit_face}.
+        #
+        # @param face_dir [String, Pathname] explicit per-face directory
+        # @param report [Models::Audit::AuditReport]
+        # @return [Pathname] the face directory written
+        def emit_face_at(face_dir, report)
+          @index_emitter.emit(face_dir, report, universal_set_root: @universal_set_root)
+          report.blocks.each { |b| @block_emitter.emit(face_dir, b) }
+          report.plane_summaries.each { |p| @plane_emitter.emit(face_dir, p) }
+          report.scripts.each { |s| @script_emitter.emit(face_dir, s) }
+          emit_codepoints(face_dir, report) if @verbose
+          emit_glyphs(face_dir, report)     if @with_glyphs
+          emit_browsers(face_dir, report)   if @emit_browser
+          face_dir
+        end
+
+        private
+
+        def emit_browsers(face_dir, report)
+          emit_face_browser(face_dir, report)
+          emit_missing_glyph_pages(face_dir, report) if @with_missing_glyph_pages
+        end
+
+        def emit_face_browser(face_dir, report)
+          Ucode::Audit::Browser::FacePage.new(
+            report: report,
+            verbose: @verbose,
+            with_glyphs: @with_glyphs,
+            universal_set_root: @universal_set_root,
+            face_dir: face_dir,
+          ).write(face_dir)
+        end
+
+        def emit_missing_glyph_pages(face_dir, report)
+          panel = Ucode::Audit::Browser::GlyphPanel.new(universal_set_root: @universal_set_root)
+          report.blocks.each do |block|
+            next if block.missing_codepoints.empty?
+
+            Ucode::Audit::Browser::MissingGlyphPage.new(
+              block_name: block.name,
+              missing_codepoints: block.missing_codepoints,
+              glyph_panel: panel,
+            ).write(face_dir)
+          end
+        end
+
+        def emit_library_browser(summary)
+          Ucode::Audit::Browser::LibraryPage.new(summary: summary).write(@output_root)
+        end
+
+        def emit_codepoints(face_dir, report)
+          report.blocks.each do |block|
+            next if block.covered_codepoints.empty?
+
+            @codepoint_emitter.emit(face_dir, block,
+                                    database: @database,
+                                    with_glyph_paths: @with_glyphs)
+          end
+        end
+
+        def emit_glyphs(face_dir, report)
+          report.blocks.flat_map(&:covered_codepoints).sort.each do |cp|
+            @glyph_emitter.emit(face_dir, cp)
+          end
+        end
+
+        def face_label(report)
+          report.postscript_name || File.basename(report.source_file, ".*")
+        end
+
+        def sanitize(name)
+          (name || "face").to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/emitter/glyph_emitter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/repo/atomic_writes"
+require "ucode/audit/emitter/paths"
+
+module Ucode
+  module Audit
+    module Emitter
+      # Writes `<face_dir>/glyphs/U+XXXX.svg` — the SVG outline of one
+      # audited glyph, emitted only in `--with-glyphs` mode.
+      #
+      # Glyph production is delegated to a caller-injected
+      # `glyph_resolver` proc. The proc takes a codepoint Integer and
+      # returns either an SVG string (write it) or nil (skip — no glyph
+      # available). ucode 0.2 ships with a default proc that always
+      # returns nil; the canonical 4-tier resolver (TODO 20) replaces it
+      # with the real fontist/fontisan + Last-Resort pipeline.
+      #
+      # Lazy by design: the resolver is invoked once per codepoint, and
+      # only for codepoints the caller actually iterates. No upfront
+      # font-load cost.
+      class GlyphEmitter
+        include Ucode::Repo::AtomicWrites
+
+        DEFAULT_RESOLVER = proc { |_codepoint| }
+
+        # @param glyph_resolver [Proc(Integer) -> String, nil] SVG source
+        def initialize(glyph_resolver: DEFAULT_RESOLVER)
+          @glyph_resolver = glyph_resolver
+        end
+
+        # @param face_dir [String, Pathname]
+        # @param codepoint [Integer]
+        # @return [Boolean] true if written, false if skipped (no glyph
+        #   available, or content-identical to existing file)
+        def emit(face_dir, codepoint)
+          svg = @glyph_resolver.call(codepoint)
+          return false if svg.nil?
+
+          path = Paths.glyph_under(face_dir, format("U+%04X", codepoint))
+          write_atomic(path, svg)
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/emitter/index_emitter.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/repo/atomic_writes"
+require "ucode/audit/emitter/paths"
+require "ucode/models/audit/block_summary"
+
+module Ucode
+  module Audit
+    module Emitter
+      # Writes `<face_dir>/index.json` — the compact face overview the
+      # browser fetches first.
+      #
+      # Compactness rules (per `03-directory-output-spec.md`):
+      #
+      #   - `codepoint_details` never appears in `index.json`. The verbose
+      #     per-block detail is emitted by {CodepointEmitter}.
+      #   - `covered_codepoints` is dropped from each block entry. The
+      #     browser fetches `codepoints/<NAME>.json` for that.
+      #   - `missing_codepoints` is kept per block — it's the actionable
+      #     gap list and small in practice.
+      #   - Adds a derived `totals` block so a renderer doesn't have to
+      #     re-aggregate to draw the headline numbers.
+      #
+      # Idempotent via {Ucode::Repo::AtomicWrites}.
+      class IndexEmitter
+        include Ucode::Repo::AtomicWrites
+
+        # @param face_dir [String, Pathname]
+        # @param report [Models::Audit::AuditReport]
+        # @param universal_set_root [String, Pathname, nil] when both
+        #   this and `face_dir` are present and the root exists on
+        #   disk, the index embeds a `universal_set` section with
+        #   relative paths to the manifest + glyphs dir. nil otherwise.
+        # @return [Boolean] true if the file was written, false if skipped
+        def emit(face_dir, report, universal_set_root: nil)
+          payload = to_pretty_json(build_index(report, universal_set_root: universal_set_root,
+                                                       face_dir: face_dir))
+          write_atomic(Paths.index_under(face_dir), payload)
+        end
+
+        # Build the index.json shape (a Hash) for a report. Exposed so
+        # the HTML browser ({Browser::FacePage}) can reuse the exact
+        # same shape when inlining overview data into its template.
+        #
+        # @param report [Models::Audit::AuditReport]
+        # @param universal_set_root [String, Pathname, nil]
+        # @param face_dir [String, Pathname, nil] required when
+        #   `universal_set_root` is supplied (relative path resolution).
+        # @return [Hash]
+        def build_index(report, universal_set_root: nil, face_dir: nil)
+          {
+            "generated_at" => report.generated_at,
+            "ucode_version" => report.ucode_version,
+            "font" => font_section(report),
+            "baseline" => report.baseline&.to_hash,
+            "totals" => build_totals(report),
+            "discrepancies" => report.discrepancies.map(&:to_hash),
+            "plane_summaries" => report.plane_summaries.map(&:to_hash),
+            "block_summaries" => block_summaries(report),
+            "script_summaries" => report.scripts.map(&:to_hash),
+            "universal_set" => universal_set_section(universal_set_root, face_dir),
+          }.compact
+        end
+
+        private
+
+        def font_section(report)
+          {
+            "source_file" => report.source_file,
+            "source_sha256" => report.source_sha256,
+            "source_format" => report.source_format,
+            "font_index" => report.font_index,
+            "num_fonts_in_source" => report.num_fonts_in_source,
+            "family_name" => report.family_name,
+            "subfamily_name" => report.subfamily_name,
+            "full_name" => report.full_name,
+            "postscript_name" => report.postscript_name,
+            "version" => report.version,
+            "font_revision" => report.font_revision,
+            "weight_class" => report.weight_class,
+            "width_class" => report.width_class,
+            "italic" => report.italic,
+            "bold" => report.bold,
+            "panose" => report.panose,
+            "total_codepoints" => report.total_codepoints,
+            "total_glyphs" => report.total_glyphs,
+            "cmap_subtables" => report.cmap_subtables,
+            "codepoint_ranges" => report.codepoint_ranges.map(&:to_hash),
+          }
+        end
+
+        def block_summaries(report)
+          report.blocks.map do |block|
+            hash = block.to_hash.except("covered_codepoints")
+            # Spec: per-block `missing_codepoints` is always embedded.
+            # lutaml-model omits empty arrays by default; re-add the key.
+            hash["missing_codepoints"] = block.missing_codepoints
+            hash
+          end
+        end
+
+        def build_totals(report)
+          {
+            "assigned_codepoints_total" => assigned_total(report),
+            "covered_codepoints_total" => report.total_codepoints,
+            "blocks_touched" => report.blocks.size,
+            "blocks_complete" => report.blocks.count do |b|
+              b.status == Models::Audit::BlockSummary::STATUS_COMPLETE
+            end,
+            "blocks_partial" => report.blocks.count do |b|
+              b.status == Models::Audit::BlockSummary::STATUS_PARTIAL
+            end,
+            "scripts_touched" => report.scripts.size,
+          }
+        end
+
+        def assigned_total(report)
+          report.blocks.sum(&:total_assigned)
+        end
+
+        def universal_set_section(root, face_dir)
+          return nil if root.nil? || face_dir.nil?
+
+          root_path = Pathname.new(root)
+          unless root_path.directory?
+            return {
+              "available" => false,
+              "reason" => "universal_set_root not found: #{root}",
+            }
+          end
+
+          {
+            "available" => true,
+            "manifest_path" => relative_path(face_dir, root_path.join("manifest.json")),
+            "glyphs_dir" => "#{relative_path(face_dir, root_path.join('glyphs'))}/",
+          }
+        end
+
+        def relative_path(from_dir, to_path)
+          to_path.expand_path.relative_path_from(Pathname.new(from_dir).expand_path).to_s
+        rescue ArgumentError
+          to_path.to_s
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/emitter/library_emitter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/repo/atomic_writes"
+require "ucode/audit/emitter/paths"
+
+module Ucode
+  module Audit
+    module Emitter
+      # Writes `output/font_audit/index.json` — the library-mode
+      # top-level index pointing at each face's `index.json`.
+      #
+      # Aggregates the per-face {Models::Audit::LibrarySummary} into a
+      # compact card list. The browser fetches this once on load and
+      # uses the cards to render the library browser; clicking a card
+      # fetches that face's per-face directory.
+      class LibraryEmitter
+        include Ucode::Repo::AtomicWrites
+
+        # @param output_root [String, Pathname]
+        # @param summary [Models::Audit::LibrarySummary]
+        # @return [Boolean] true if written, false if skipped
+        def emit(output_root, summary)
+          path = Paths.library_index_path(output_root)
+          payload = to_pretty_json(build_index(summary))
+          write_atomic(path, payload)
+        end
+
+        # Build the library index.json shape (a Hash). Exposed so the
+        # HTML browser ({Browser::LibraryPage}) can reuse the exact
+        # same shape when inlining overview data into its template.
+        #
+        # @param summary [Models::Audit::LibrarySummary]
+        # @return [Hash]
+        def build_index(summary)
+          {
+            "root_path" => summary.root_path,
+            "total_files" => summary.total_files,
+            "total_faces" => summary.total_faces,
+            "scanned_extensions" => summary.scanned_extensions,
+            "aggregate_metrics" => summary.aggregate_metrics,
+            "license_distribution" => summary.license_distribution,
+            "duplicate_groups" => summary.duplicate_groups.map(&:to_hash),
+            "script_coverage" => summary.script_coverage.map(&:to_hash),
+            "faces" => face_cards(summary),
+          }
+        end
+
+        private
+
+        def face_cards(summary)
+          summary.per_face_reports.map do |report|
+            label = face_label(report)
+            covered_total, assigned_total, complete, partial = block_rollup(report)
+            {
+              "label" => label,
+              "family_name" => report.family_name,
+              "postscript_name" => report.postscript_name,
+              "weight_class" => report.weight_class,
+              "total_codepoints" => report.total_codepoints,
+              "total_glyphs" => report.total_glyphs,
+              "covered_total" => covered_total,
+              "total_assigned_total" => assigned_total,
+              "blocks_complete" => complete,
+              "blocks_partial" => partial,
+              "source_sha256" => report.source_sha256,
+              "index_path" => "#{label}/index.json",
+              "html_path" => "#{label}/index.html",
+            }
+          end
+        end
+
+        def block_rollup(report)
+          covered = 0
+          assigned = 0
+          complete = 0
+          partial = 0
+          report.blocks.each do |b|
+            covered += b.covered_count
+            assigned += b.total_assigned
+            case b.status
+            when Models::Audit::BlockSummary::STATUS_COMPLETE then complete += 1
+            when Models::Audit::BlockSummary::STATUS_PARTIAL  then partial  += 1
+            end
+          end
+          [covered, assigned, complete, partial]
+        end
+
+        def face_label(report)
+          report.postscript_name || File.basename(report.source_file, ".*")
+        end
+      end
+    end
+  end
+end