fontisan 0.4.7 → 0.4.9

data/docs/cli/audit.md

@@ -1,337 +0,0 @@
----
-title: audit
----
-
-# audit
-
-Produce a complete per-face font audit report — identity, style, metrics,
-coverage, licensing, hinting, color capabilities, variable-font detail,
-OpenType layout features, and Unicode/CLDR aggregation.
-
-`audit` is the successor to `otfinfo`: it covers everything `otfinfo`
-reports plus a great deal more (coverage, hinting, color, variation,
-layout, language coverage), and supports collections, compare mode, and
-whole-library summaries.
-
-## Quick Reference
-
-```bash
-# One face
-fontisan audit FONT.ttf
-
-# Collection (one report per face)
-fontisan audit COLLECTION.ttc
-
-# Whole library
-fontisan audit DIR/ --recursive --summary
-
-# Compare two fonts or saved reports
-fontisan audit --compare A.ttf B.ttf
-```
-
-## Variants
-
-| Variant | What it does | Output |
-|---------|-------------|--------|
-| `audit FONT.ttf` | One AuditReport for the single face | `AuditReport` |
-| `audit COLLECTION.ttc` | One AuditReport per face (in source order) | `Array<AuditReport>` |
-| `audit DIR/ --recursive --summary` | Walk the directory, summarize the library | `LibrarySummary` |
-| `audit --compare A B` | Diff two faces or two saved reports | `AuditDiff` |
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--format FORMAT` | Output format: `text` (default), `yaml`, `json` |
-| `--output PATH`, `-o` | Write to a directory (collection/library), a file (single/compare), or stdout |
-| `--font-index N` | Audit only face N of a collection (default: all) |
-| `--brief` | Fast inventory — skip metrics/hinting/color/layout/UCD/CLDR |
-| `--all-codepoints` | Include the full per-codepoint list (defaults to a compact range view) |
-| `--ucd-version VER` | Aggregate against this UCD version (`latest` to probe) |
-| `--with-language-coverage` | Compute CLDR language coverage % (auto-downloads CLDR on first use) |
-| `--cldr-version VER` | CLDR version to use (`latest` to probe) |
-| `--compare` | Diff two inputs (requires exactly two paths) |
-| `--recursive` | Library mode: walk into subdirectories |
-| `--summary` | Library mode: produce a `LibrarySummary` over a directory |
-
-## Brief Mode
-
-`--brief` runs only the cheap name-table extractors (provenance, identity,
-style, licensing, coverage) and skips metrics, hinting, color,
-variation, OpenType layout, UCD block/script aggregation, and CLDR
-language coverage. Useful for taking a fast inventory of large libraries.
-
-```bash
-fontisan audit FONT.ttf --brief
-fontisan audit DIR/ --recursive --summary --brief
-```
-
-Note: `audit --brief` is distinct from `info --brief`. `info --brief`
-loads only 6 tables; `audit --brief` still loads the full font (Coverage
-reads `cmap`) but selects a cheaper extractor subset.
-
-## Single-Face Audit
-
-```bash
-# Text formatter (default)
-fontisan audit FONT.ttf
-
-# YAML (machine-readable)
-fontisan audit FONT.ttf --format yaml
-
-# JSON
-fontisan audit FONT.ttf --format json | jq '.licensing'
-
-# Write to disk
-fontisan audit FONT.ttf -o report.yaml
-```
-
-Sample text output (truncated):
-
-```
-NotoSans-Regular
-================================================================================
-generated_at: 2026-06-24T18:11:39Z      fontisan: 0.2.20
-source_sha256: f5f552c8c5edb61fe6efb824baf4d4de47b1a8689ab4925ff43f7bd6a4ebece5
-source_file:   /path/to/NotoSans-Regular.ttf
-source_format: ttf                      layout: single face (1/1)
-
-IDENTITY
-  Family:           Noto Sans
-  Subfamily:        Regular
-  Full name:        Noto Sans Regular
-  PostScript:       NotoSans-Regular
-  Version:          Version 2.015; ttfautohint (v1.8.4.7-5d5b)
-  Revision:         2.0149993896484375
-
-STYLE
-  Weight class:     400 (Regular)
-  Width class:      5 (Medium)
-  Bold:             no
-  Italic:           no
-  PANOSE:           2 11 5 2 4 5 4 2 2 4
-
-COVERAGE
-  Codepoints:       3094
-  Glyphs:           4515
-  cmap subtables:   4, 12
-  Ranges (top 10):  U+0000-U+0000, U+000D-U+000D, U+0020-U+007E, ...
-  Unicode scripts:  Latin, ...
-
-LICENSING
-  License URL:      https://scripts.sil.org/OFL
-  Embedding:        0x0000 (Editable embedding)
-
-METRICS
-  Units per em:     1000
-  Ascender:         1160
-  Descender:        -288
-  ...
-
-UNICODE BLOCKS
-  Basic Latin                   95 / 128   74.2%
-  Latin-1 Supplement            96 / 128   75.0%
-  ...
-
-VARIABLE FONT
-  Axes:             wght (100–900, default 400)
-  Named instances:  9
-
-OPENTYPE LAYOUT
-  Scripts:          latn, cyrl, grek, ...
-  Features:         c2sc, calt, case, dlig, dnom, frac, kern, liga, ...
-
-LANGUAGE COVERAGE
-  en:  99.2%
-  fr:  97.4%
-  ...
-```
-
-## Collections
-
-For TTC/OTC/dfont, one report is produced per face in source order.
-
-```bash
-# Audit every face
-fontisan audit COLLECTION.ttc
-
-# Audit only face 2
-fontisan audit COLLECTION.ttc --font-index 2
-
-# Write one file per face into a directory
-fontisan audit COLLECTION.ttc -o reports/
-
-# Resulting files use the postscript name with a 2-digit index prefix:
-# 00-NotoSans-Regular.yaml
-# 01-NotoSans-Bold.yaml
-# 02-NotoSerif-Italic.yaml
-```
-
-## Compare Mode
-
-`--compare` diffs two inputs. Each input is one of:
-
-- A previously saved audit report (`.yaml` / `.yml` / `.json`)
-- A font file (audited on-the-fly)
-
-Mixed inputs are allowed — useful for tracking a font's evolution
-against a checked-in baseline.
-
-```bash
-# Two live fonts
-fontisan audit --compare a.ttf b.ttf
-
-# Saved baseline vs. live
-fontisan audit --compare baseline.yaml new.ttf
-
-# Two saved reports
-fontisan audit --compare v1.yaml v2.yaml -o diff.yaml
-```
-
-The output is an `AuditDiff` containing:
-
-- `field_changes` — scalar field-level changes (e.g. weight_class 400 → 700)
-- `codepoints` — added/removed/unchanged codepoint counts
-- `added_features` / `removed_features`
-- `added_scripts` / `removed_scripts`
-- `added_blocks` / `removed_blocks`
-- `added_languages` / `removed_languages`
-
-## Library Mode
-
-Point `audit` at a directory with `--recursive` and/or `--summary` to
-scan a whole library of fonts.
-
-```bash
-# Flat directory
-fontisan audit lib/ --summary
-
-# Walk subdirectories
-fontisan audit lib/ --recursive --summary
-
-# YAML for downstream processing
-fontisan audit lib/ --recursive --summary --format yaml -o library.yaml
-```
-
-The output is a `LibrarySummary` containing:
-
-- `root_path`, `total_files`, `total_faces`, `scanned_extensions`
-- `aggregate_metrics` — total codepoints/glyphs/bytes summed across faces
-- `script_coverage` — per-script face counts and lists
-- `duplicate_groups` — files grouped by `source_sha256` (size > 1)
-- `license_distribution` — face counts per `license_url`
-- `per_face_reports` — the full per-face reports used to aggregate
-
-Files that fail to load (corrupt, unsupported) are listed on stderr as
-`skipped <path>` and excluded from the summary.
-
-## UCD Aggregation
-
-By default, audit aggregates codepoints against the configured-default
-UCD version, producing:
-
-- `blocks` — per-Unicode-block coverage rows (name, range, total, covered, fill_ratio, complete)
-- `unicode_scripts` — distinct scripts present in the font
-
-Override with `--ucd-version`:
-
-```bash
-# Use a specific UCD version
-fontisan audit FONT.ttf --ucd-version 16.0.0
-
-# Probe and use the latest
-fontisan audit FONT.ttf --ucd-version latest
-```
-
-Manage the local UCD cache with `fontisan ucd`:
-
-```bash
-fontisan ucd status
-fontisan ucd list
-fontisan ucd download 17.0.0
-```
-
-## CLDR Language Coverage
-
-`--with-language-coverage` computes per-language coverage % using CLDR
-exemplar sets. The first invocation downloads the CLDR data
-(~MBs); subsequent invocations use the cache.
-
-```bash
-fontisan audit FONT.ttf --with-language-coverage
-
-# Use a specific CLDR version
-fontisan audit FONT.ttf --with-language-coverage --cldr-version 45
-```
-
-Manage the CLDR cache with `fontisan cldr`:
-
-```bash
-fontisan cldr status
-fontisan cldr list
-fontisan cldr download 45
-```
-
-## Ruby API
-
-### Single face
-
-```ruby
-require "fontisan"
-
-# Returns an AuditReport for a single font, or an Array<AuditReport>
-# for a collection (one per face).
-report = Fontisan::Commands::AuditCommand.new("font.ttf",
-                                              ucd_version: "17.0.0").run
-
-puts report.family_name
-puts report.total_codepoints
-puts report.licensing.license_url
-puts report.blocks.first.fill_ratio
-```
-
-### Compare
-
-```ruby
-diff = Fontisan::Commands::AuditCompareCommand.new(
-  "baseline.yaml", "new.ttf", ucd_version: "17.0.0"
-).run
-
-diff.field_changes.each { |c| puts "#{c.field}: #{c.left} → #{c.right}" }
-puts "added codepoints: #{diff.codepoints.added_count}"
-```
-
-### Library summary
-
-```ruby
-cmd = Fontisan::Commands::AuditLibraryCommand.new(
-  "lib/", recursive: true, options: { ucd_version: "17.0.0" }
-)
-summary = cmd.run
-cmd.skipped.each { |path| warn "skipped #{path}" }
-
-summary.script_coverage.each do |row|
-  puts "#{row.script}: #{row.face_count} faces"
-end
-summary.duplicate_groups.each do |group|
-  puts "duplicate #{group.source_sha256[0,8]}: #{group.files.join(', ')}"
-end
-```
-
-### Brief mode
-
-```ruby
-# Use the audit_brief: key (NOT brief:, which would trigger metadata-only
-# font loading via BaseCommand).
-report = Fontisan::Commands::AuditCommand.new(
-  "font.ttf", audit_brief: true, ucd_version: "17.0.0"
-).run
-```
-
-## Related Commands
-
-- [info](/cli/info) — Lighter-weight font metadata (replaces `otfinfo -i`)
-- [tables](/cli/tables) — Raw OpenType table listing
-- [features](/cli/features) — Just GSUB/GPOS features
-- [scripts](/cli/scripts) — Just supported scripts
-- [validate](/cli/validate) — Pass/fail quality checks (audit is descriptive; validate is prescriptive)

data/lib/fontisan/cldr/aggregator.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Fontisan
-  module Cldr
-    # Produces audit-ready per-language coverage from a codepoint list
-    # and a Cldr::Index of per-language exemplar sets.
-    #
-    # Pure: no I/O, no side effects.
-    module Aggregator
-      module_function
-
-      # @param codepoints [Enumerable<Integer>] font's codepoints
-      # @param languages_index [Cldr::Index]
-      # @return [Array<Models::Cldr::LanguageCoverage>] sorted by
-      #   descending coverage_ratio, then by language name
-      def aggregate(codepoints, languages_index)
-        font_set = Set.new(codepoints)
-
-        languages_index.entries.map do |lang, required_set|
-          covered = (font_set & required_set).size
-          total = required_set.size
-          Models::Cldr::LanguageCoverage.new(
-            language: lang,
-            covered: covered,
-            total: total,
-            coverage_ratio: total.zero? ? 0.0 : covered.fdiv(total).round(4),
-            fully_supported: total.positive? && covered == total,
-          )
-        end.sort_by { |lc| [lc.coverage_ratio * -1, lc.language] }
-      end
-    end
-  end
-end

data/lib/fontisan/cldr/cache_manager.rb

@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-require "pathname"
-
-module Fontisan
-  module Cldr
-    # Manages the on-disk CLDR cache layout.
-    #
-    # Cache root resolution honors `XDG_CONFIG_HOME` per the XDG Base
-    # Directory Specification. Falls back to `~/.config` on Unix.
-    #
-    # Layout:
-    #
-    #   <root>/
-    #     <version>/
-    #       json/                 # extracted CLDR JSON archive
-    #         cldr-json/
-    #           cldr-characters-full/
-    #             main/<lang>/characters.json
-    #       index/
-    #         languages.yml       # built index of per-language codepoint sets
-    #
-    # No network access — all methods are pure filesystem operations.
-    module CacheManager
-      LANGUAGES_INDEX_FILENAME = "languages.yml"
-      private_constant :LANGUAGES_INDEX_FILENAME
-
-      class << self
-        # Root path of the CLDR cache.
-        # @return [Pathname]
-        def root
-          base = xdg_config_home || File.join(Dir.home, ".config")
-          Pathname.new(base).join("fontisan", "cldr")
-        end
-
-        # Per-version directory.
-        # @param version [String] e.g. "46.0.0"
-        # @return [Pathname]
-        def version_dir(version)
-          root.join(version)
-        end
-
-        # Directory where the raw CLDR JSON archive is extracted.
-        # @param version [String]
-        # @return [Pathname]
-        def json_dir(version)
-          version_dir(version).join("json")
-        end
-
-        # Directory containing the per-language characters.json files
-        # inside the extracted archive.
-        # @param version [String]
-        # @return [Pathname]
-        def characters_main_dir(version)
-          json_dir(version).join("cldr-json", "cldr-characters-full", "main")
-        end
-
-        # Directory holding the derived language index for a version.
-        # @param version [String]
-        # @return [Pathname]
-        def index_dir(version)
-          version_dir(version).join("index")
-        end
-
-        def languages_index_path(version)
-          index_dir(version).join(LANGUAGES_INDEX_FILENAME)
-        end
-
-        # True if the extracted JSON archive is present for this version.
-        # @param version [String]
-        # @return [Boolean]
-        def cached?(version)
-          characters_main_dir(version).exist?
-        end
-
-        # All versions currently in the cache (sorted ascending).
-        # @return [Array<String>]
-        def cached_versions
-          return [] unless root.exist?
-
-          root.children.select(&:directory?).map { |p| p.basename.to_s }.sort
-        end
-
-        # Create the version directory and json/index subdirs.
-        # Idempotent.
-        # @param version [String]
-        def ensure_version_dir!(version)
-          json_dir(version).mkpath
-          index_dir(version).mkpath
-        end
-
-        # Remove a version from the cache. No-op if absent.
-        # @param version [String]
-        def remove_version(version)
-          dir = version_dir(version)
-          dir.rmtree if dir.exist?
-        end
-
-        private
-
-        def xdg_config_home
-          env = ENV["XDG_CONFIG_HOME"]
-          return nil if env.nil? || env.empty?
-
-          env
-        end
-      end
-    end
-  end
-end

data/lib/fontisan/cldr/config.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-
-module Fontisan
-  module Cldr
-    # Single source of truth for CLDR version selection.
-    #
-    # Wraps `lib/fontisan/config/cldr.yml`. Loads the YAML once at first
-    # access and memoizes. All other Cldr::* classes resolve versions,
-    # URLs, and known-version validation through this module.
-    module Config
-      CONFIG_PATH = File.expand_path("../config/cldr.yml", __dir__)
-      private_constant :CONFIG_PATH
-
-      class << self
-        # The CLDR version Fontisan uses by default for auto-download and
-        # `fontisan cldr download` (no args). String like "46.0.0".
-        def default_version
-          data[:default_version]
-        end
-
-        # Array of CLDR version strings this Fontisan release recognizes.
-        # Used by VersionResolver to reject unknown versions early.
-        def known_versions
-          data[:known_versions]
-        end
-
-        # Base URL for fetching CLDR JSON artifacts.
-        def base_url
-          data[:base_url]
-        end
-
-        # Listing URL for `--latest` probing.
-        def listing_url
-          data[:listing_url]
-        end
-
-        # Full URL to the CLDR JSON full archive for a version.
-        # @param version [String] e.g. "46.0.0"
-        # @return [String]
-        def archive_url_for(version)
-          "#{base_url}/#{version}/cldr-#{version}-json-full.zip"
-        end
-
-        # True if the version appears in `known_versions`.
-        def known?(version)
-          known_versions.include?(version)
-        end
-
-        private
-
-        def data
-          @data ||= YAML.load_file(CONFIG_PATH).transform_keys(&:to_sym)
-        end
-      end
-    end
-  end
-end

data/lib/fontisan/cldr/download_error.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Fontisan
-  module Cldr
-    # Raised by Cldr::Downloader when the upstream HTTP fetch or the zip
-    # extraction fails. Caught by AuditCommand to degrade-with-warning.
-    class DownloadError < Cldr::Error; end
-  end
-end

data/lib/fontisan/cldr/downloader.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "uri"
-require "tempfile"
-require "zip"
-
-module Fontisan
-  module Cldr
-    # Fetches CLDR JSON archives from unicode-org/cldr-json GitHub releases
-    # and unpacks them into the cache.
-    #
-    # Single entry point: `Downloader.download(version, force:)`.
-    # Idempotent unless `force: true`. Returns the path to the extracted
-    # `main/` characters directory.
-    module Downloader
-      class << self
-        # Download and unpack CLDR JSON for `version`.
-        #
-        # @param version [String] e.g. "46.0.0"
-        # @param force [Boolean] if false and cache already has the
-        #   extracted files, return without re-fetching.
-        # @return [Pathname] path to the extracted main/ characters dir
-        # @raise [DownloadError] on HTTP failure or zip extraction failure
-        def download(version, force: false)
-          target = CacheManager.characters_main_dir(version)
-          return target if target.exist? && !force
-
-          CacheManager.ensure_version_dir!(version)
-          zip_data = fetch_zip(version)
-          extract_archive(zip_data, CacheManager.json_dir(version))
-          target
-        end
-
-        private
-
-        def fetch_zip(version)
-          uri = URI(Config.archive_url_for(version))
-          response = Net::HTTP.get_response(uri)
-          unless response.is_a?(Net::HTTPSuccess)
-            raise DownloadError,
-                  "GET #{uri} returned HTTP #{response.code}: #{response.message}"
-          end
-
-          body = response.body
-          if body.nil? || body.empty?
-            raise DownloadError, "GET #{uri} returned an empty body"
-          end
-
-          body
-        rescue StandardError => e
-          raise e if e.is_a?(DownloadError)
-
-          raise DownloadError, "Failed to fetch #{uri}: #{e.message}"
-        end
-
-        def extract_archive(zip_data, target_dir)
-          Tempfile.create(["fontisan-cldr", ".zip"]) do |tmp|
-            tmp.binmode
-            tmp.write(zip_data)
-            tmp.flush
-            tmp.rewind
-
-            target_dir.mkpath
-            Zip::File.open(tmp.path) do |zip|
-              zip.each do |entry|
-                next unless entry.file?
-
-                out = target_dir.join(entry.name)
-                out.dirname.mkpath
-                entry.extract(out.to_s) { true } # overwrite
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/fontisan/cldr/error.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Fontisan
-  module Cldr
-    # Base error class for all CLDR-related failures.
-    class Error < StandardError; end
-  end
-end

data/lib/fontisan/cldr/index.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-module Fontisan
-  module Cldr
-    # In-memory per-language codepoint lookup.
-    #
-    # Loads a YAML index of `{language: [codepoint, ...]}`. Each language's
-    # codepoints are stored as a Set<Integer> for O(1) intersection checks.
-    #
-    # Used by {Cldr::Aggregator} to compute per-language coverage %.
-    class Index
-      include Enumerable
-
-      # @param entries [Hash{String=>Set<Integer>, Array<Integer>}]
-      def initialize(entries = {})
-        @entries = entries.transform_values do |cps|
-          cps.is_a?(Set) ? cps : Set.new(cps)
-        end
-      end
-
-      # @return [Hash{String=>Set<Integer>}]
-      attr_reader :entries
-
-      def each(&)
-        @entries.each(&)
-      end
-
-      def size
-        @entries.size
-      end
-
-      def languages
-        @entries.keys.sort
-      end
-
-      # @param language [String]
-      # @return [Set<Integer>, nil]
-      def lookup(language)
-        @entries[language]
-      end
-
-      def include?(language)
-        @entries.key?(language)
-      end
-
-      # Serialize to a YAML file.
-      # @param path [String, Pathname]
-      # @return [void]
-      def save(path)
-        File.open(path, "w") do |file|
-          YAML.dump(@entries.transform_values(&:sort), file)
-        end
-      end
-
-      # Load from a YAML file previously written by #save.
-      # @param path [String, Pathname]
-      # @return [Index]
-      def self.load(path)
-        hash = YAML.load_file(path)
-        new(hash)
-      end
-    end
-  end
-end