ucode 0.1.0 → 0.1.1

data/lib/ucode/commands/audit/compare_command.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "json"
+
+require "ucode/audit"
+require "ucode/audit/differ"
+require "ucode/audit/face_auditor"
+require "ucode/audit/formatters"
+require "ucode/glyphs/real_fonts"
+
+module Ucode
+  module Commands
+    module Audit
+      # `ucode audit compare LEFT RIGHT` — diff two audits.
+      #
+      # Each of LEFT and RIGHT can be:
+      #   - A path to a font file (audited on-the-fly with
+      #     {Audit::FaceAuditor}).
+      #   - A path to a face audit directory — its `index.json` is
+      #     read for the precomputed report shape.
+      #   - A path to a saved `index.json` file directly.
+      #
+      # Note: reading from disk only recovers the *derived* overview
+      # shape from {Emitter::IndexEmitter}, not a full AuditReport.
+      # The compare therefore uses the field subset that the
+      # overview shape preserves (identity + coverage totals). For a
+      # full-feature diff, audit both inputs fresh from their font
+      # paths.
+      class CompareCommand
+        Result = Struct.new(:left_source, :right_source, :diff, :text,
+                            :error, keyword_init: true)
+
+        # @param left [String] font path | audit dir | index.json path
+        # @param right [String] same forms as left
+        # @param unicode_version [String, nil]
+        # @param output_file [String, Pathname, nil] write text to file
+        #   (default: stdout, captured as `text` in the result)
+        # @return [Result]
+        def call(left, right, unicode_version: nil, output_file: nil)
+          left_report = load_or_audit(left, unicode_version: unicode_version)
+          right_report = load_or_audit(right, unicode_version: unicode_version)
+
+          diff = Ucode::Audit::Differ.new(left_report, right_report).diff
+          text = Ucode::Audit::Formatters::AuditDiffText.new(diff).render
+
+          write_output(text, output_file) if output_file
+
+          Result.new(left_source: left, right_source: right, diff: diff,
+                     text: text)
+        rescue StandardError => e
+          Result.new(left_source: left, right_source: right,
+                     error: "#{e.class}: #{e.message}")
+        end
+
+        private
+
+        def load_or_audit(spec, unicode_version:)
+          case resolve_kind(spec)
+          when :font_file  then audit_freshly(spec, unicode_version: unicode_version)
+          when :audit_dir  then load_overview(Pathname.new(spec).join("index.json"))
+          when :index_json then load_overview(Pathname.new(spec))
+          end
+        end
+
+        # Heuristic: a path is an index.json if it ends in `.json`;
+        # an audit directory if it doesn't end in `.json` and isn't
+        # a font file; a font file otherwise.
+        def resolve_kind(spec)
+          path = Pathname.new(spec)
+          return :index_json if path.file? && path.extname == ".json"
+          return :audit_dir  if path.directory?
+          return :audit_dir  if path.join("index.json").exist?
+
+          :font_file
+        end
+
+        def audit_freshly(font_path, unicode_version:)
+          options = {}
+          options[:ucd_version] = unicode_version if unicode_version
+          Ucode::Audit::FaceAuditor.new(font_path.to_s, options: options).call
+        end
+
+        # Reconstructs a partial AuditReport from the derived overview
+        # shape. Only the fields Differ consults are populated; others
+        # are nil. This is best-effort — see class docs.
+        def load_overview(index_json_path)
+          hash = JSON.parse(index_json_path.read)
+          font = hash["font"] || {}
+          totals = hash["totals"] || {}
+          Models::Audit::AuditReport.new(
+            source_file: font["source_file"],
+            source_sha256: font["source_sha256"],
+            family_name: font["family_name"],
+            subfamily_name: font["subfamily_name"],
+            full_name: font["full_name"],
+            postscript_name: font["postscript_name"],
+            version: font["version"],
+            font_revision: font["font_revision"],
+            weight_class: font["weight_class"],
+            width_class: font["width_class"],
+            italic: font["italic"],
+            bold: font["bold"],
+            panose: font["panose"],
+            total_codepoints: totals["covered_codepoints_total"] || font["total_codepoints"],
+            total_glyphs: font["total_glyphs"],
+            codepoint_ranges: codepoint_ranges(font["codepoint_ranges"]),
+            scripts: scripts(hash["script_summaries"]),
+            blocks: blocks(hash["block_summaries"]),
+            baseline: baseline(hash["baseline"]),
+            plane_summaries: plane_summaries(hash["plane_summaries"]),
+            discrepancies: [],
+          )
+        end
+
+        def codepoint_ranges(arr)
+          return [] unless arr
+
+          arr.map do |h|
+            Models::Audit::CodepointRange.new(
+              first_cp: h["first_cp"], last_cp: h["last_cp"],
+            )
+          end
+        end
+
+        def scripts(arr)
+          return [] unless arr
+
+          arr.map do |h|
+            Models::Audit::ScriptSummary.new(
+              script_code: h["script_code"], script_name: h["script_name"],
+              blocks_total: h["blocks_total"], assigned_total: h["assigned_total"],
+              covered_total: h["covered_total"], coverage_percent: h["coverage_percent"],
+              status: h["status"],
+            )
+          end
+        end
+
+        def blocks(arr)
+          return [] unless arr
+
+          arr.map do |h|
+            Models::Audit::BlockSummary.new(
+              name: h["name"], first_cp: h["first_cp"], last_cp: h["last_cp"],
+              range: h["range"], plane: h["plane"],
+              total_assigned: h["total_assigned"],
+              covered_count: h["covered_count"],
+              missing_count: h["missing_count"],
+              coverage_percent: h["coverage_percent"],
+              status: h["status"],
+            )
+          end
+        end
+
+        def baseline(hash)
+          return nil unless hash
+
+          Models::Audit::Baseline.new(
+            unicode_version: hash["unicode_version"],
+            ucode_version: hash["ucode_version"],
+            fontisan_version: hash["fontisan_version"],
+            source: hash["source"],
+            generated_at: hash["generated_at"],
+          )
+        end
+
+        def plane_summaries(arr)
+          return [] unless arr
+
+          arr.map do |h|
+            Models::Audit::PlaneSummary.new(
+              plane: h["plane"], blocks_total: h["blocks_total"],
+              assigned_total: h["assigned_total"],
+              covered_total: h["covered_total"],
+              coverage_percent: h["coverage_percent"],
+            )
+          end
+        end
+
+        def write_output(text, target)
+          path = Pathname.new(target)
+          path.dirname.mkpath
+          path.write(text)
+        end
+      end
+    end
+  end
+end

data/lib/ucode/commands/audit/font_command.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "fileutils"
+
+require "ucode/glyphs/real_fonts"
+require "ucode/audit"
+require "ucode/audit/face_auditor"
+require "ucode/audit/emitter/face_directory"
+require "ucode/audit/emitter/paths"
+
+module Ucode
+  module Commands
+    module Audit
+      # `ucode audit font PATH` — audit a single font file or
+      # fontist-resolvable name. Writes the per-face directory tree
+      # under `<output_root>/font_audit/<label>/`.
+      #
+      # Auto-detects collection sources (TTC/OTC/dfong) and falls
+      # through to collection-style emission in that case — one tree
+      # per face. For an explicit, intent-revealing form, use
+      # {CollectionCommand}.
+      #
+      # Pure: Thor never touches this. Real work is delegated to
+      # {Glyphs::RealFonts::FontLocator} (resolve spec → path),
+      # {Audit::FaceAuditor} (build report), and
+      # {Audit::Emitter::FaceDirectory} (write tree).
+      class FontCommand
+        FaceOutcome = Struct.new(:label, :postscript_name, :output_dir,
+                                 keyword_init: true)
+
+        Result = Struct.new(:spec, :label, :output_dir, :faces, :error,
+                            keyword_init: true)
+
+        # @param spec [String] font spec — direct path, or `label=path`,
+        #   or a fontist formula name.
+        # @param label [String, nil] output label override. Defaults
+        #   to the report's postscript_name, or the file basename.
+        # @param unicode_version [String, nil] baseline UCD version.
+        # @param verbose [Boolean] emit per-codepoint detail chunks.
+        # @param with_glyphs [Boolean] emit per-codepoint SVG chunks
+        #   (no-op until TODO 20 wires the 4-tier resolver).
+        # @param brief [Boolean] cheap-extractor-only mode.
+        # @param output_root [String, Pathname] parent directory; the
+        #   audit root is `<output_root>/font_audit`.
+        # @param browse [Boolean] also write the HTML browsers.
+        # @param install [Boolean] allow fontist install on miss.
+        # @param reference [Ucode::Audit::CoverageReference, nil] the
+        #   baseline to compare against (TODO 25). When nil, defaults
+        #   to UCD-only inside {FaceAuditor}.
+        # @param universal_set_root [String, Pathname, nil] forwarded
+        #   to {Emitter::FaceDirectory} for the face browser's
+        #   universal-set section (TODO 26).
+        # @param with_missing_glyph_pages [Boolean] forward per-block
+        #   standalone missing-glyph galleries (TODO 26).
+        # @return [Result]
+        def call(spec, output_root:, label: nil, unicode_version: nil, verbose: false,
+                 with_glyphs: false, brief: false, browse: false,
+                 install: true, reference: nil,
+                 universal_set_root: nil, with_missing_glyph_pages: false)
+          located = locate(spec, install: install)
+          reports = Array(audit_faces(located.path, unicode_version: unicode_version,
+                                                    brief: brief, reference: reference))
+
+          face_label = label || derived_face_label(reports.first, located)
+          sanitized = sanitize(face_label)
+
+          directory = Ucode::Audit::Emitter::FaceDirectory.new(
+            output_root: output_root,
+            verbose: verbose,
+            with_glyphs: with_glyphs,
+            emit_browser: browse,
+            universal_set_root: universal_set_root,
+            with_missing_glyph_pages: with_missing_glyph_pages,
+          )
+
+          face_outcomes, top_dir =
+            if reports.one?
+              emit_standalone(directory, sanitized, reports.first)
+            else
+              emit_collection(directory, sanitized, reports, output_root)
+            end
+
+          Result.new(spec: spec, label: face_label, output_dir: top_dir.to_s,
+                     faces: face_outcomes)
+        rescue StandardError => e
+          Result.new(spec: spec, error: "#{e.class}: #{e.message}")
+        end
+
+        private
+
+        def locate(spec, install:)
+          Ucode::Glyphs::RealFonts::FontLocator.new.locate(spec, install: install)
+        end
+
+        def audit_faces(path, unicode_version:, brief:, reference: nil)
+          options = audit_options(unicode_version: unicode_version, brief: brief)
+          mode = brief ? :brief : :full
+          Ucode::Audit::FaceAuditor.new(path, options: options, mode: mode,
+                                              reference: reference).call
+        end
+
+        def audit_options(unicode_version:, brief:)
+          opts = {}
+          opts[:ucd_version] = unicode_version if unicode_version
+          opts[:audit_brief] = true if brief
+          opts
+        end
+
+        def derived_face_label(report, located)
+          report&.postscript_name || located.name || File.basename(located.path.to_s, ".*")
+        end
+
+        def emit_standalone(directory, label, report)
+          face_dir = directory.emit_face(label: label, report: report)
+          outcome = FaceOutcome.new(label: label,
+                                    postscript_name: report.postscript_name,
+                                    output_dir: face_dir.to_s)
+          [[outcome], face_dir]
+        end
+
+        def emit_collection(directory, source_label, reports, output_root)
+          subdirs = directory.emit_collection(source_label: source_label,
+                                              reports: reports)
+          top = Ucode::Audit::Emitter::Paths.face_dir(output_root, source_label)
+          outcomes = reports.zip(subdirs).map do |report, name|
+            FaceOutcome.new(label: name,
+                            postscript_name: report.postscript_name,
+                            output_dir: top.join(name).to_s)
+          end
+          [outcomes, top]
+        end
+
+        def sanitize(name)
+          (name || "face").to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+        end
+      end
+    end
+  end
+end

data/lib/ucode/commands/audit/library_command.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/audit"
+require "ucode/audit/library_auditor"
+require "ucode/audit/emitter/face_directory"
+require "ucode/audit/emitter/paths"
+
+module Ucode
+  module Commands
+    module Audit
+      # `ucode audit library DIR` — walk a directory of fonts and
+      # produce one per-face audit plus a library-level rollup.
+      #
+      # Delegates directory walking + per-face audit to
+      # {Audit::LibraryAuditor}, then writes the per-face trees +
+      # library-level `index.json` via {Audit::Emitter::FaceDirectory}.
+      class LibraryCommand
+        SkippedFile = Struct.new(:path, :reason, keyword_init: true)
+
+        Result = Struct.new(:root, :total_files, :total_faces, :output_dir,
+                            :skipped, :error, keyword_init: true)
+
+        # @param dir [String, Pathname] directory containing fonts.
+        # @param recursive [Boolean] walk subdirectories.
+        # @param unicode_version [String, nil] baseline UCD version.
+        # @param verbose [Boolean] per-codepoint detail chunks per face.
+        # @param with_glyphs [Boolean] per-codepoint SVG chunks.
+        # @param brief [Boolean] cheap-extractor-only mode.
+        # @param output_root [String, Pathname] parent of the audit root.
+        # @param browse [Boolean] also write library + face HTML browsers.
+        # @param reference [Ucode::Audit::CoverageReference, nil] baseline
+        #   forwarded to every per-face audit (TODO 25).
+        # @param universal_set_root [String, Pathname, nil] forwarded to
+        #   {Emitter::FaceDirectory} for the face browser's
+        #   universal-set section (TODO 26).
+        # @param with_missing_glyph_pages [Boolean] emit per-block
+        #   standalone missing-glyph galleries per face (TODO 26).
+        # @return [Result]
+        def call(dir, output_root:, recursive: false, unicode_version: nil, verbose: false,
+                 with_glyphs: false, brief: false, browse: false, reference: nil,
+                 universal_set_root: nil, with_missing_glyph_pages: false)
+          options = library_options(unicode_version: unicode_version, brief: brief)
+          auditor = Ucode::Audit::LibraryAuditor.new(dir, recursive: recursive,
+                                                          options: options,
+                                                          reference: reference)
+          summary = auditor.audit
+
+          directory = Ucode::Audit::Emitter::FaceDirectory.new(
+            output_root: output_root,
+            verbose: verbose,
+            with_glyphs: with_glyphs,
+            emit_browser: browse,
+            universal_set_root: universal_set_root,
+            with_missing_glyph_pages: with_missing_glyph_pages,
+          )
+          directory.emit_library(summary: summary)
+
+          Result.new(
+            root: dir.to_s,
+            total_files: summary.total_files,
+            total_faces: summary.total_faces,
+            output_dir: Ucode::Audit::Emitter::Paths.library_root(output_root).to_s,
+            skipped: auditor.skipped.map { |s| parse_skipped(s) },
+          )
+        rescue StandardError => e
+          Result.new(root: dir.to_s, error: "#{e.class}: #{e.message}")
+        end
+
+        private
+
+        def library_options(unicode_version:, brief:)
+          opts = {}
+          opts[:ucd_version] = unicode_version if unicode_version
+          opts[:audit_brief] = true if brief
+          opts
+        end
+
+        def parse_skipped(entry)
+          path, _, reason = entry.rpartition(": ")
+          SkippedFile.new(path: path, reason: reason)
+        end
+      end
+    end
+  end
+end

data/lib/ucode/commands/audit/reference_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ucode
+  module Commands
+    module Audit
+      # Translates CLI flags into a {Ucode::Audit::CoverageReference}.
+      #
+      # The audit CLI exposes the universal-set reference via a
+      # `--reference-universal-set=<path>` flag (and a default lookup
+      # at `output/universal_glyph_set/manifest.json`). This builder
+      # resolves the flag value into a concrete reference instance
+      # backed by a freshly-opened {Ucode::Database}, so the command
+      # classes don't repeat the same branching.
+      #
+      # Behavior:
+      #
+      # - flag = "none"          → nil (force UCD-only even if a default manifest exists)
+      # - flag = path to .json   → {Ucode::Audit::UniversalSetReference}
+      # - flag = nil             → look at DEFAULT_MANIFEST_PATH; use it if present,
+      #                             else nil (UCD-only)
+      module ReferenceBuilder
+        DEFAULT_MANIFEST_PATH = Pathname.new("output/universal_glyph_set/manifest.json")
+
+        module_function
+
+        # @param flag [String, nil] value of the
+        #   `--reference-universal-set` CLI option.
+        # @param version [String, nil] UCD version for the database
+        #   that backs the reference. When nil, the default UCD
+        #   version is resolved.
+        # @return [Ucode::Audit::CoverageReference, nil]
+        def build(flag:, version: nil)
+          return nil if flag == "none"
+
+          path = resolve_manifest_path(flag)
+          return nil unless path && File.exist?(path)
+
+          database = open_database(version)
+          return nil unless database
+
+          Ucode::Audit::UniversalSetReference.new(
+            manifest: path, database: database,
+          )
+        end
+
+        def resolve_manifest_path(flag)
+          return Pathname.new(flag) if flag && flag != "none"
+          return DEFAULT_MANIFEST_PATH if DEFAULT_MANIFEST_PATH.exist?
+
+          nil
+        end
+
+        def open_database(version)
+          resolved = version || Ucode::VersionResolver.resolve(nil)
+          Ucode::Database.open(resolved)
+        rescue Ucode::UnknownVersionError, Ucode::DatabaseMissingError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ucode/commands/audit.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Commands
+    # `ucode audit *` command classes. Pure Ruby — Thor (in
+    # `lib/ucode/cli.rb`) is responsible only for argument parsing
+    # and dispatch. Each class here is a structured-result command
+    # that delegates to the {Ucode::Audit} pipeline
+    # ({Audit::FaceAuditor}, {Audit::LibraryAuditor}, {Audit::Differ},
+    # {Audit::Emitter::FaceDirectory}, {Audit::Browser::*}).
+    module Audit
+      autoload :FontCommand,       "ucode/commands/audit/font_command"
+      autoload :CollectionCommand, "ucode/commands/audit/collection_command"
+      autoload :LibraryCommand,    "ucode/commands/audit/library_command"
+      autoload :CompareCommand,    "ucode/commands/audit/compare_command"
+      autoload :BrowserCommand,    "ucode/commands/audit/browser_command"
+      autoload :ReferenceBuilder,  "ucode/commands/audit/reference_builder"
+    end
+  end
+end

data/lib/ucode/commands/block_feed.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/repo"
+require "ucode/version_resolver"
+
+module Ucode
+  module Commands
+    # `ucode block-feed` — emit a compact per-block Unicode data feed
+    # from ucode's canonical output tree.
+    #
+    # Reads ucode's `output/` and produces three artifacts at the target
+    # directory:
+    #
+    #   <target>/unicode-blocks.json
+    #   <target>/unicode-version.json
+    #   <target>/unicode/blocks/<slug>.json
+    #
+    # Each per-block file contains the codepoints in that block with
+    # their compact Unicode metadata (name, general category, script,
+    # combining class, bidi class, mirrored flag). Block slugs are
+    # derived from the block name via the standard slug algorithm.
+    class BlockFeedCommand
+      Result = Struct.new(:ucode_output_root, :block_feed_output_root,
+                          :unicode_version, :blocks_written,
+                          :codepoints_written, :unicode_blocks_path,
+                          :unicode_version_path, keyword_init: true)
+
+      # @param ucode_output_root [String, Pathname] ucode's `output/`
+      #   (must contain blocks/index.json, blocks/<ID>/index.json,
+      #   index/labels.json).
+      # @param block_feed_output_root [String, Pathname] target directory.
+      # @param unicode_version [String, nil] UCD version to stamp on
+      #   unicode-version.json. Defaults to the version recorded in
+      #   ucode's manifest.json.
+      # @return [Result]
+      def call(ucode_output_root:, block_feed_output_root:, unicode_version: nil)
+        ucode_root = Pathname.new(ucode_output_root)
+        feed_root = Pathname.new(block_feed_output_root)
+        version = unicode_version || manifest_version(ucode_root)
+
+        emitter = Repo::BlockFeedEmitter.new(ucode_root, feed_root)
+        outcome = emitter.emit(ucd_version: version)
+
+        Result.new(
+          ucode_output_root: ucode_root.to_s,
+          block_feed_output_root: feed_root.to_s,
+          unicode_version: version,
+          blocks_written: outcome[:blocks_written],
+          codepoints_written: outcome[:codepoints_written],
+          unicode_blocks_path: outcome[:unicode_blocks_path],
+          unicode_version_path: outcome[:unicode_version_path],
+        )
+      end
+
+      private
+
+      def manifest_version(ucode_root)
+        manifest = ucode_root.join("manifest.json")
+        return default_version unless manifest.exist?
+
+        JSON.parse(manifest.read)["ucd_version"] || default_version
+      rescue JSON::ParserError
+        default_version
+      end
+
+      def default_version
+        VersionResolver.resolve(nil)
+      end
+    end
+  end
+end