fontisan 0.2.16 → 0.2.22

data/lib/fontisan/cli/ucd_cli.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Fontisan
+  # Thor subcommand for managing the local UCD (Unicode Character
+  # Database) cache used by `fontisan audit`.
+  #
+  #   fontisan ucd download [VERSION]   fetch + index UCDXML
+  #   fontisan ucd status               show what's cached
+  #   fontisan ucd path [VERSION]       print local cache path
+  #   fontisan ucd list                 list known versions
+  #   fontisan ucd remove VERSION       delete a cached version
+  #
+  # With no arguments, `download` resolves the configured default version
+  # (see lib/fontisan/config/ucd.yml).
+  class UcdCli < Thor
+    desc "download [VERSION]",
+         "Download and index UCDXML (default: configured default version)"
+    option :force, type: :boolean, default: false,
+                   desc: "Re-download even if already cached"
+    option :latest, type: :boolean, default: false,
+                    desc: "Probe unicode.org for the latest version"
+    # Download (and index) UCDXML for a version.
+    #
+    # @param version [String, nil] explicit version, or omit for default
+    def download(version = nil)
+      intent = resolve_intent(version, options[:latest])
+      actual = Ucd::VersionResolver.resolve(intent)
+
+      path = Ucd::Downloader.download(actual, force: options[:force])
+      Ucd::IndexBuilder.build(actual) unless index_present?(actual)
+      puts "UCD #{actual} ready at: #{path}"
+    rescue Ucd::Error => e
+      warn "ERROR: #{e.message}"
+      exit 1
+    end
+
+    desc "status", "Show cached UCD versions and default version"
+    # Print a one-screen summary of the local cache state.
+    def status
+      cached = Ucd::CacheManager.cached_versions
+      puts "Default version: #{Ucd::Config.default_version}"
+      puts "Cache root:      #{Ucd::CacheManager.root}"
+      puts "Cached versions: #{cached.empty? ? '(none)' : cached.join(', ')}"
+    end
+
+    desc "path [VERSION]", "Print local cache directory for a version"
+    # Print the cache directory path for a version (default: default version).
+    #
+    # @param version [String, nil]
+    def path(version = nil)
+      actual = Ucd::VersionResolver.resolve(version)
+      puts Ucd::CacheManager.version_dir(actual)
+    rescue Ucd::UnknownVersionError => e
+      warn "ERROR: #{e.message}"
+      exit 1
+    end
+
+    desc "list", "List UCD versions known to this Fontisan release"
+    # Print the curated list of versions this Fontisan release supports.
+    def list
+      Ucd::Config.known_versions.each { |v| puts v }
+    end
+
+    desc "remove VERSION", "Remove a cached UCD version"
+    # Delete one cached version. No-op if absent.
+    #
+    # @param version [String]
+    def remove(version)
+      Ucd::VersionResolver.validate!(version)
+      unless Ucd::CacheManager.cached?(version)
+        warn "Version #{version} is not cached; nothing to remove."
+        return
+      end
+
+      Ucd::CacheManager.remove_version(version)
+      puts "Removed UCD #{version}."
+    rescue Ucd::UnknownVersionError => e
+      warn "ERROR: #{e.message}"
+      exit 1
+    end
+
+    private
+
+    def resolve_intent(version, latest)
+      return :latest if latest && version.nil?
+
+      version
+    end
+
+    def index_present?(version)
+      Ucd::CacheManager.blocks_index_path(version).exist? &&
+        Ucd::CacheManager.scripts_index_path(version).exist?
+    end
+  end
+end

data/lib/fontisan/cli.rb

@@ -25,6 +25,93 @@ module Fontisan
                          desc: "Suppress non-error output",
                          aliases: "-q"
 
+    desc "ucd", "Manage local UCD cache (subcommands)", hide: true
+    subcommand "ucd", UcdCli
+
+    desc "cldr", "Manage local CLDR cache (subcommands)", hide: true
+    subcommand "cldr", CldrCli
+
+    desc "audit PATH", "Produce a per-face font audit report, or diff/summarize"
+    long_desc <<~DESC
+      Produce a complete per-face font audit report covering identity, style,
+      metrics, coverage (Unicode blocks/scripts), licensing, hinting, color
+      capabilities, variable font detail, and OpenType layout features.
+
+      For TTC/OTC/dfont collections, one report per face is produced. Use
+      --output to write reports to disk; --font-index to audit a single face.
+
+      Variants:
+        fontisan audit FONT.ttf
+        fontisan audit COLLECTION.ttc
+        fontisan audit DIR/ --recursive --summary
+        fontisan audit --compare A.ttf B.ttf
+        fontisan audit --compare A.yaml B.yaml
+
+      Output formats: text (default), yaml, json.
+
+      Use --brief for a fast inventory pass that skips metrics, hinting,
+      color, variable-font detail, OpenType layout, and UCD/CLDR
+      aggregation — only identity, style, licensing, and codepoint coverage.
+    DESC
+    option :font_index, type: :numeric,
+                        desc: "Audit only this face in a collection (default: all)"
+    option :all_codepoints, type: :boolean, default: false,
+                            desc: "Include the full per-codepoint list " \
+                                  "(defaults to compact range view)"
+    option :ucd_version, type: :string,
+                         desc: "UCD version to aggregate against " \
+                               "(default: configured default; 'latest' to probe)"
+    option :with_language_coverage, type: :boolean, default: false,
+                                    desc: "Compute coverage % per CLDR language " \
+                                          "(requires CLDR cache; auto-downloads)"
+    option :cldr_version, type: :string,
+                          desc: "CLDR version (default: configured default; " \
+                                "'latest' to probe)"
+    option :brief, type: :boolean, default: false,
+                   desc: "Skip metrics/hinting/color/layout/UCD/CLDR for a " \
+                         "fast inventory pass"
+    option :compare, type: :boolean, default: false,
+                     desc: "Diff two fonts or two saved reports " \
+                           "(requires exactly two PATHs)"
+    option :recursive, type: :boolean, default: false,
+                       desc: "Audit every font under a directory tree " \
+                             "(library mode)"
+    option :summary, type: :boolean, default: false,
+                     desc: "Produce a LibrarySummary over a directory of fonts"
+    option :output, type: :string,
+                    desc: "Output directory (collections/library) or file " \
+                          "(single font / compare)",
+                    aliases: "-o"
+    # Produce a complete font audit report, or diff two fonts/reports,
+    # or summarize a whole library.
+    #
+    # @param paths [Array<String>] one path (audit/library), or two paths (--compare)
+    def audit(*paths)
+      raise Thor::Error, "audit requires one PATH (or two with --compare)" if paths.empty?
+
+      if options[:compare]
+        unless paths.length == 2
+          raise Thor::Error,
+                "audit --compare requires exactly two paths"
+        end
+
+        return run_compare(paths[0], paths[1])
+      end
+
+      raise Thor::Error, "audit requires exactly one PATH" unless paths.length == 1
+
+      path = paths[0]
+      if Dir.exist?(path) && !library_mode?(path)
+        raise Thor::Error,
+              "audit on a directory requires --recursive or --summary"
+      end
+      return run_library_audit(path) if library_mode?(path)
+
+      run_single_audit(path)
+    rescue Errno::ENOENT, Error, Thor::Error => e
+      handle_error(e)
+    end
+
     desc "info PATH", "Display font information"
     option :brief, type: :boolean, default: false,
                    desc: "Brief mode - only essential info (5x faster, uses metadata loading)",
@@ -203,7 +290,9 @@ module Fontisan
 
     desc "convert FONT_FILE", "Convert font to different format"
     option :to, type: :string, required: true,
-                desc: "Target format (ttf, otf, type1, t1, woff, woff2)",
+                desc: "Target format: ttf, otf, type1, t1, ttc, otc, dfont, svg, " \
+                      "woff (zlib — works on all browsers incl. legacy), " \
+                      "woff2 (Brotli — ~30% smaller, modern browsers only)",
                 aliases: "-t"
     option :output, type: :string,
                     desc: "Output file path (required unless --show-options)",
@@ -255,6 +344,19 @@ module Fontisan
                              desc: "Enable table optimization"
     option :decompose_on_output, type: :boolean,
                                  desc: "Decompose on output (generating option)"
+    # Compression knobs — declared by each strategy (single source of truth:
+    # Converters::* strategies). Cross-format misuse is caught at convert time
+    # by FormatConverter.validate_options_for_target! with a clear ArgumentError.
+    option :zlib_level, type: :numeric,
+                        desc: "WOFF only: zlib compression level (0–9, default 6)"
+    option :uncompressed, type: :boolean,
+                          desc: "WOFF only: store tables uncompressed (legal per WOFF 1.0 §5.1)"
+    option :compression_threshold, type: :numeric,
+                                   desc: "WOFF only: skip compression for tables smaller than N bytes (default 100)"
+    option :brotli_quality, type: :numeric,
+                            desc: "WOFF2 only: Brotli quality (0–11, default 11)"
+    option :transform_tables, type: :boolean,
+                              desc: "WOFF2 only: apply glyf/loca and hmtx transformations"
     # Convert a font to a different format using the universal transformation pipeline.
     #
     # Supported conversions:
@@ -264,6 +366,14 @@ module Fontisan
     # - Variable fonts: Automatic variation preservation or instance generation
     # - Collections (TTC/OTC/dfont): Preserve mixed TTF+OTF by default, or standardize with --target-format
     #
+    # Web fonts — WOFF vs WOFF2:
+    # WOFF uses zlib compression and works on every browser that supports
+    # web fonts at all (IE9+, all evergreen browsers). WOFF2 uses Brotli and
+    # is ~30% smaller but requires modern browsers (Chrome 36+, Firefox 39+,
+    # Safari 12+, Edge 14+). Old browsers cannot decode Brotli, so for legacy
+    # support serve WOFF. Tune knobs with --zlib-level / --brotli-quality /
+    # --uncompressed (WOFF only) / --transform-tables (WOFF2 only).
+    #
     # Collection Format Support:
     # TTC, OTC, and dfont all support mixed TrueType and OpenType fonts. By default, original font formats
     # are preserved during collection conversion (--target-format preserve). Use --target-format ttf to
@@ -678,6 +788,96 @@ module Fontisan
       puts output unless options[:quiet]
     end
 
+    # Write audit reports to disk. If `target` is a directory (or there are
+    # multiple reports), one file per face is written under it. If `target`
+    # is a file path and there's exactly one report, that exact path is used.
+    #
+    # @param reports [Array<Models::Audit::AuditReport>]
+    # @param target [String] directory (collection) or file path (single)
+    # @param format [String] "yaml" or "json"
+    # @return [void]
+    def write_audit_outputs(reports, target, format)
+      sym_format = format.to_sym
+
+      if reports.one? && !Dir.exist?(target) && File.extname(target) != ""
+        File.write(target, serialize_report(reports.first, sym_format))
+        puts "Wrote #{target}" unless options[:quiet]
+        return
+      end
+
+      paths = Commands::AuditCommand.write_reports(reports, to: target,
+                                                            format: sym_format)
+      paths.each { |p| puts "Wrote #{p}" unless options[:quiet] }
+    end
+
+    def run_single_audit(path)
+      cmd_options = options.dup
+      cmd_options.delete(:output)
+      # Audit's --brief selects a cheap extractor subset but still needs FULL
+      # font loading (Coverage reads cmap). Translate to :audit_brief so
+      # BaseCommand's :brief → METADATA shortcut does not fire.
+      cmd_options[:audit_brief] = cmd_options.delete(:brief) if cmd_options.key?(:brief)
+      command = Commands::AuditCommand.new(path, cmd_options)
+      reports = Array(command.run)
+
+      if options[:output]
+        write_audit_outputs(reports, options[:output], options[:format])
+      else
+        reports.each { |r| output_result(r) }
+      end
+    end
+
+    def run_compare(left_path, right_path)
+      cmd = Commands::AuditCompareCommand.new(left_path, right_path, options)
+      diff = cmd.run
+      return if options[:quiet]
+
+      if options[:output]
+        File.write(options[:output], serialize_report(diff, options[:format].to_sym))
+        puts "Wrote #{options[:output]}"
+        return
+      end
+
+      output_result(diff)
+    end
+
+    def run_library_audit(path)
+      cmd = Commands::AuditLibraryCommand.new(
+        path,
+        recursive: options[:recursive],
+        options: options.dup,
+      )
+      summary = cmd.run
+      announce_skipped(cmd.skipped)
+      return if options[:quiet]
+
+      if options[:output]
+        File.write(options[:output],
+                   serialize_report(summary, options[:format].to_sym))
+        puts "Wrote #{options[:output]}"
+        return
+      end
+
+      output_result(summary)
+    end
+
+    # Library mode triggers when the path is a directory and either
+    # --recursive or --summary is requested. A single-file audit ignores
+    # both flags (a TTC is audited face-by-face via run_single_audit).
+    def library_mode?(path)
+      Dir.exist?(path) && (options[:recursive] || options[:summary])
+    end
+
+    def announce_skipped(skipped)
+      return if skipped.empty?
+
+      skipped.each { |p| warn "skipped #{p}" }
+    end
+
+    def serialize_report(report, format)
+      format == :json ? report.to_json : report.to_yaml
+    end
+
     # Format result as human-readable text.
     #
     # @param result [Object] The result object to format
@@ -720,7 +920,6 @@ module Fontisan
     #
     # @return [void]
     def list_available_tests
-      require_relative "validators/profile_loader"
       profiles = Validators::ProfileLoader.all_profiles
       puts "Available validation profiles:"
       profiles.each do |profile_name, config|

data/lib/fontisan/collection/builder.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "table_analyzer"
-require_relative "table_deduplicator"
-require_relative "offset_calculator"
-require_relative "writer"
 require "yaml"
 
 module Fontisan

data/lib/fontisan/collection/dfont_builder.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../font_writer"
-require_relative "../error"
-require_relative "../validation/collection_validator"
-
 module Fontisan
   module Collection
     # DfontBuilder creates Apple dfont (Data Fork Font) resource fork structures

data/lib/fontisan/collection/shared_logic.rb

@@ -15,8 +15,6 @@ module Fontisan
       # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Array of fonts
       # @return [Models::TableSharingInfo] Sharing statistics
       def calculate_table_sharing_for_fonts(fonts)
-        require_relative "../models/table_sharing_info"
-
         # Build table hash map (checksum -> size)
         table_map = {}
         total_table_size = 0

data/lib/fontisan/collection/writer.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../constants"
-require_relative "../utilities/checksum_calculator"
-
 module Fontisan
   module Collection
     # CollectionWriter writes binary TTC/OTC files

data/lib/fontisan/collection.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Autoload hub for the Fontisan::Collection namespace.
+
+module Fontisan
+  module Collection
+    autoload :Builder, "fontisan/collection/builder"
+    autoload :DfontBuilder, "fontisan/collection/dfont_builder"
+    autoload :OffsetCalculator, "fontisan/collection/offset_calculator"
+    autoload :SharedLogic, "fontisan/collection/shared_logic"
+    autoload :TableAnalyzer, "fontisan/collection/table_analyzer"
+    autoload :TableDeduplicator, "fontisan/collection/table_deduplicator"
+    autoload :Writer, "fontisan/collection/writer"
+  end
+end

data/lib/fontisan/commands/audit_command.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Fontisan
+  module Commands
+    # Produces a complete per-face font audit report.
+    #
+    # One AuditReport per face. For standalone fonts (TTF/OTF/WOFF/WOFF2),
+    # #run returns a single AuditReport. For collections (TTC/OTC/dfont),
+    # #run returns an Array<AuditReport> — one per face, in source order.
+    #
+    # The report is assembled by running every extractor in
+    # {Audit::Registry} against an {Audit::Context}. Each extractor
+    # owns one concern (provenance, identity, style, coverage,
+    # aggregations, …). Adding a new concern means adding one
+    # extractor class and one line in the registry — AuditCommand
+    # itself never changes.
+    class AuditCommand < BaseCommand
+      # @return [Models::Audit::AuditReport, Array<Models::Audit::AuditReport>]
+      def run
+        if FontLoader.collection?(@font_path)
+          audit_collection
+        else
+          audit_face(@font, 0, 1)
+        end
+      end
+
+      # Write one file per face under `to` (a directory). Pure utility —
+      # operates on a pre-built reports array, no font_path required.
+      #
+      # @param reports [Array<Models::Audit::AuditReport>]
+      # @param to [String] output directory; created if missing
+      # @param format [Symbol] :yaml or :json
+      # @return [Array<String>] written file paths
+      def self.write_reports(reports, to:, format: :yaml)
+        FileUtils.mkdir_p(to)
+
+        reports.map do |report|
+          path = File.join(to, output_filename(report, format))
+          content = format == :json ? report.to_json : report.to_yaml
+          File.write(path, content)
+          path
+        end
+      end
+
+      # Compute the per-face filename for a report.
+      #
+      # @param report [Models::Audit::AuditReport]
+      # @param format [Symbol] :yaml or :json
+      # @return [String] filename only (no directory)
+      def self.output_filename(report, format)
+        ext = format == :json ? "json" : "yaml"
+        base = if report.num_fonts_in_source == 1
+                 safe_filename(report.postscript_name || report.family_name || "font")
+               else
+                 format("%<idx>02d-%<name>s",
+                        idx: report.font_index,
+                        name: safe_filename(report.postscript_name || "face"))
+               end
+        "#{base}.#{ext}"
+      end
+
+      # Sanitize an arbitrary string into a filesystem-safe basename.
+      #
+      # @param name [String, nil]
+      # @return [String]
+      def self.safe_filename(name)
+        return "font" if name.nil? || name.empty?
+
+        name.gsub(/[^A-Za-z0-9._-]/, "_")
+      end
+
+      private
+
+      def audit_collection
+        collection = FontLoader.load_collection(@font_path)
+        num = collection.num_fonts
+        Array.new(num) do |index|
+          font = FontLoader.load(@font_path, font_index: index,
+                                             mode: LoadingModes::FULL)
+          audit_face(font, index, num)
+        end
+      end
+
+      def audit_face(font, font_index, num_fonts_in_source)
+        context = Audit::Context.new(
+          font: font,
+          font_path: @font_path,
+          font_index: font_index,
+          num_fonts_in_source: num_fonts_in_source,
+          options: @options,
+        )
+
+        fields = {}
+        Audit::Registry.each(mode: audit_mode) do |extractor_class|
+          fields.merge!(extractor_class.new.extract(context))
+        end
+
+        fields[:warning] = combine_warnings(
+          context.ucd[:warning],
+          context.cldr&.dig(:warning),
+        )
+
+        Models::Audit::AuditReport.new(**fields)
+      end
+
+      # Audit's --brief selects a cheap extractor subset (identity, style,
+      # licensing, coverage) but still requires FULL font loading — the
+      # Coverage extractor reads `cmap`. The CLI translates the user-facing
+      # `--brief` flag into `:audit_brief` so BaseCommand's `:brief →
+      # LoadingModes::METADATA` shortcut doesn't fire.
+      def audit_mode
+        @options[:audit_brief] ? :brief : :full
+      end
+
+      def combine_warnings(*warnings)
+        compacted = warnings.flatten.compact
+        compacted.empty? ? nil : compacted.join("; ")
+      end
+    end
+  end
+end

data/lib/fontisan/commands/audit_compare_command.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Commands
+    # Diffs two faces or two saved audit reports.
+    #
+    # Each input is one of:
+    #   - A path to a `.yaml`/`.json` file previously written by
+    #     `fontisan audit -o`. Loaded as an AuditReport.
+    #   - A path to a font file. Audited on-the-fly via AuditCommand.
+    #
+    # Returns an {Models::Audit::AuditDiff}. The CLI renders it as
+    # YAML/JSON (text formatter lands in TODO 25).
+    #
+    # Mixed inputs are allowed (font vs. saved report), which is useful
+    # for tracking a font's evolution against a checked-in baseline.
+    class AuditCompareCommand
+      # @param left_path [String] path to font file or saved report
+      # @param right_path [String] path to font file or saved report
+      # @param options [Hash] forwarded to AuditCommand for any input
+      #   that needs to be audited fresh
+      def initialize(left_path, right_path, options = {})
+        @left_path = left_path
+        @right_path = right_path
+        @options = options
+      end
+
+      # @return [Models::Audit::AuditDiff]
+      def run
+        left_report = load_report(@left_path)
+        right_report = load_report(@right_path)
+        Audit::Differ.new(left_report, right_report).diff
+      end
+
+      private
+
+      def load_report(path)
+        if saved_report?(path)
+          load_saved_report(path)
+        else
+          AuditCommand.new(path, audit_options).run
+        end
+      end
+
+      def saved_report?(path)
+        ext = File.extname(path).downcase
+        [".yaml", ".yml", ".json"].include?(ext)
+      end
+
+      def load_saved_report(path)
+        case File.extname(path).downcase
+        when ".json"
+          Models::Audit::AuditReport.from_json(File.read(path))
+        else
+          Models::Audit::AuditReport.from_yaml(File.read(path))
+        end
+      end
+
+      # Forward only the audit-relevant options when auditing fresh fonts.
+      # Drops `--compare` (consumed here) and `--output` (no file output).
+      def audit_options
+        @options.except(:compare, :output)
+      end
+    end
+  end
+end

data/lib/fontisan/commands/audit_library_command.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Commands
+    # Audits every font in a directory (tree) and rolls the per-face
+    # reports up into a {Models::Audit::LibrarySummary}.
+    #
+    # Thin wrapper over {Audit::LibraryAuditor}: validates the root
+    # path exists, delegates to the auditor, returns the summary.
+    # The auditor itself owns file discovery and per-face auditing;
+    # this command is the CLI-facing boundary that maps user-facing
+    # options onto auditor inputs.
+    class AuditLibraryCommand
+      # @param root_path [String] directory containing fonts
+      # @param recursive [Boolean] walk into subdirectories
+      # @param options [Hash] forwarded to AuditCommand for each face
+      def initialize(root_path, recursive:, options:)
+        @root_path = root_path
+        @recursive = recursive
+        @options = options
+      end
+
+      # @return [Models::Audit::LibrarySummary]
+      def run
+        raise Error, "library audit requires an existing directory: #{@root_path}" unless Dir.exist?(@root_path)
+
+        auditor.audit
+      end
+
+      # @return [Array<String>] files skipped during the audit pass
+      def skipped
+        auditor.skipped
+      end
+
+      private
+
+      def auditor
+        @auditor ||= Audit::LibraryAuditor.new(
+          @root_path,
+          recursive: @recursive,
+          options: @options,
+        )
+      end
+    end
+  end
+end

data/lib/fontisan/commands/base_command.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../font_loader"
-require_relative "../error"
-
 module Fontisan
   module Commands
     # Abstract base class for all CLI commands.