fontisan 0.4.33 → 0.4.34

data/lib/fontisan/commands/audit_command.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Fontisan
+  module Commands
+    # Produces a structured {Models::AuditReport} for a single font or
+    # an array of reports for every face in a collection.
+    #
+    # The audit report is MECE with ucode: fontisan owns the font-identity
+    # axis (name table, style metadata, OpenType layout); ucode owns the
+    # Unicode-coverage axis (UCD parsing, block/script aggregation). The
+    # audit command emits the raw codepoint list so a consumer can run
+    # ucode separately without re-reading the font.
+    #
+    # Delegates data extraction to existing sub-commands and table readers
+    # — no table re-parsing happens here. This keeps the audit command a
+    # thin orchestration layer (DRY, single source of truth).
+    #
+    # @example Single font
+    #   cmd = AuditCommand.new("Inter.ttf", include_codepoints: true)
+    #   cmd.run  # => Models::AuditReport
+    #
+    # @example Collection
+    #   cmd = AuditCommand.new("Inter.ttc")
+    #   cmd.run  # => Array<Models::AuditReport>
+    class AuditCommand < BaseCommand
+      # @return [Models::AuditReport, Array<Models::AuditReport>]
+      def run
+        if FontLoader.collection?(@font_path)
+          audit_collection
+        else
+          audit_single_font(font_index: nil, num_fonts: 1)
+        end
+      end
+
+      private
+
+      # ------------------------------------------------------------------
+      # Collection dispatch
+      # ------------------------------------------------------------------
+
+      def audit_collection
+        collection = FontLoader.load_collection(@font_path)
+        num = collection.num_fonts
+        Array.new(num) do |idx|
+          face = load_face(idx)
+          build_report(face, font_index: idx, num_fonts: num)
+        end
+      end
+
+      def audit_single_font(font_index:, num_fonts:)
+        build_report(font, font_index: font_index, num_fonts: num_fonts)
+      end
+
+      # Reload a single face from a collection by index, with full tables
+      # so the audit is complete.
+      def load_face(idx)
+        FontLoader.load(@font_path, font_index: idx, mode: LoadingModes::FULL)
+      end
+
+      # ------------------------------------------------------------------
+      # Report assembly
+      # ------------------------------------------------------------------
+
+      # @param face [SfntFont] loaded font
+      # @param font_index [Integer, nil]
+      # @param num_fonts [Integer]
+      # @return [Models::AuditReport]
+      def build_report(face, font_index:, num_fonts:)
+        Models::AuditReport.new.tap do |r|
+          populate_provenance(r, font_index:, num_fonts:)
+          populate_identity(r, face)
+          populate_style(r, face)
+          populate_coverage(r, face)
+          populate_layout(r, face)
+        end
+      end
+
+      # ------------------------------------------------------------------
+      # Provenance
+      # ------------------------------------------------------------------
+
+      def populate_provenance(report, font_index:, num_fonts:)
+        report.generated_at = Time.now.utc.iso8601
+        report.fontisan_version = VERSION
+        report.source_file = File.basename(@font_path)
+        report.source_sha256 = Digest::SHA256.file(@font_path).hexdigest
+        report.source_format = detect_source_format
+        report.font_index = font_index
+        report.num_fonts_in_source = num_fonts
+      end
+
+      def detect_source_format
+        fmt = FontLoader.detect_format(@font_path)
+        fmt ? fmt.to_s : "unknown"
+      end
+
+      # ------------------------------------------------------------------
+      # Identity (name table)
+      # ------------------------------------------------------------------
+
+      def populate_identity(report, face)
+        return unless face.has_table?(Constants::NAME_TAG)
+
+        name_table = face.table(Constants::NAME_TAG)
+        report.family_name = name_table.english_name(Tables::Name::FAMILY)
+        report.subfamily_name = name_table.english_name(Tables::Name::SUBFAMILY)
+        report.full_name = name_table.english_name(Tables::Name::FULL_NAME)
+        report.postscript_name =
+          name_table.english_name(Tables::Name::POSTSCRIPT_NAME)
+        report.version = name_table.english_name(Tables::Name::VERSION)
+
+        return unless face.has_table?(Constants::HEAD_TAG)
+
+        report.font_revision = face.table(Constants::HEAD_TAG).font_revision
+      end
+
+      # ------------------------------------------------------------------
+      # Style (OS/2, head, fvar)
+      # ------------------------------------------------------------------
+
+      def populate_style(report, face)
+        report.is_variable = false
+        report.italic = false
+        report.bold = false
+        populate_os2_style(report, face) if face.has_table?(Constants::OS2_TAG)
+        populate_head_style(report, face) if face.has_table?(Constants::HEAD_TAG)
+        populate_fvar_style(report, face) if face.has_table?(Constants::FVAR_TAG)
+      end
+
+      def populate_os2_style(report, face)
+        os2 = face.table(Constants::OS2_TAG)
+        report.weight_class = os2.us_weight_class
+        report.width_class = os2.us_width_class
+        report.italic = os2.fs_selection && (os2.fs_selection & 0x01).positive?
+        report.bold = os2.fs_selection && (os2.fs_selection & 0x20).positive?
+        report.panose = format_panose(os2.panose)
+      end
+
+      def populate_head_style(report, face)
+        head = face.table(Constants::HEAD_TAG)
+        mac_style = head.mac_style || 0
+        # head macStyle overrides OS/2 fsSelection only when OS/2 didn't set it
+        report.italic = true if (mac_style & 0x02).positive?
+        report.bold = true if (mac_style & 0x01).positive?
+      end
+
+      def populate_fvar_style(report, face)
+        report.is_variable = true
+        fvar = face.table(Constants::FVAR_TAG)
+        report.axes = fvar.axes.map do |axis|
+          Models::AuditAxis.new(
+            tag: axis.axis_tag,
+            min_value: axis.min_value,
+            default_value: axis.default_value,
+            max_value: axis.max_value,
+            name_id: axis.axis_name_id,
+          )
+        end
+      end
+
+      def format_panose(panose)
+        return nil unless panose
+
+        panose.to_a.join(" ")
+      end
+
+      # ------------------------------------------------------------------
+      # Coverage (cmap + glyph count)
+      # ------------------------------------------------------------------
+
+      def populate_coverage(report, face)
+        if face.has_table?(Constants::CMAP_TAG)
+          cmap = face.table(Constants::CMAP_TAG)
+          mappings = cmap.unicode_mappings || {}
+          report.total_codepoints = mappings.size
+          report.cmap_subtables = cmap.subtable_formats
+          report.codepoints = codepoint_list(mappings.keys) if include_codepoints?
+        end
+
+        report.total_glyphs = total_glyphs(face)
+      end
+
+      def codepoint_list(codepoints)
+        codepoints.sort.map { |cp| format_codepoint(cp) }
+      end
+
+      def format_codepoint(cp)
+        format("U+%04X", cp)
+      end
+
+      def total_glyphs(face)
+        return 0 unless face.has_table?(Constants::MAXP_TAG)
+
+        face.table(Constants::MAXP_TAG)&.num_glyphs || 0
+      rescue StandardError
+        0
+      end
+
+      def include_codepoints?
+        @options.fetch(:include_codepoints, true)
+      end
+
+      # ------------------------------------------------------------------
+      # OpenType layout (GSUB/GPOS)
+      # ------------------------------------------------------------------
+
+      def populate_layout(report, face)
+        report.opentype_scripts = collect_scripts(face)
+        report.features = collect_features(face)
+      end
+
+      def collect_scripts(face)
+        scripts = Set.new
+        %w[GSUB GPOS].each do |tag|
+          next unless face.has_table?(tag)
+
+          table = face.table(tag)
+          scripts.merge(table.scripts) if table
+        end
+        scripts.sort
+      end
+
+      def collect_features(face)
+        features = Set.new
+        %w[GSUB GPOS].each do |tag|
+          next unless face.has_table?(tag)
+
+          table = face.table(tag)
+          features.merge(collect_features_from_table(table)) if table
+        end
+        features.sort
+      end
+
+      def collect_features_from_table(layout_table)
+        scripts = begin
+                    layout_table.scripts
+        rescue StandardError
+                    []
+        end
+        scripts.flat_map { |script| features_for_script(layout_table, script) }
+      rescue StandardError
+        []
+      end
+
+      def features_for_script(layout_table, script)
+        
+          layout_table.features(script_tag: script)
+      rescue StandardError
+          []
+        
+      end
+    end
+  end
+end

data/lib/fontisan/commands.rb

@@ -5,6 +5,7 @@
 module Fontisan
   module Commands
     autoload :BaseCommand, "fontisan/commands/base_command"
+    autoload :AuditCommand, "fontisan/commands/audit_command"
     autoload :ConvertCommand, "fontisan/commands/convert_command"
     autoload :DumpTableCommand, "fontisan/commands/dump_table_command"
     autoload :ExportCommand, "fontisan/commands/export_command"

data/lib/fontisan/models/audit_report.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    # Variable-font axis descriptor for the audit report.
+    class AuditAxis < Lutaml::Model::Serializable
+      attribute :tag, :string
+      attribute :min_value, :float
+      attribute :default_value, :float
+      attribute :max_value, :float
+      attribute :name_id, :integer
+
+      json do
+        map "tag", to: :tag
+        map "min_value", to: :min_value
+        map "default_value", to: :default_value
+        map "max_value", to: :max_value
+        map "name_id", to: :name_id
+      end
+
+      yaml do
+        map "tag", to: :tag
+        map "min_value", to: :min_value
+        map "default_value", to: :default_value
+        map "max_value", to: :max_value
+        map "name_id", to: :name_id
+      end
+    end
+
+    # Structured font audit report covering identity, style, coverage,
+    # and OpenType layout facts. Designed for archival use — each report
+    # is self-describing with provenance (generated_at, fontisan_version,
+    # source_sha256).
+    #
+    # The report is a value object: it captures what the font FILE
+    # declares, not what any external index says about it.
+    class AuditReport < Lutaml::Model::Serializable
+      # Provenance
+      attribute :generated_at, :string
+      attribute :fontisan_version, :string
+      attribute :source_file, :string
+      attribute :source_sha256, :string
+      attribute :source_format, :string
+      attribute :font_index, :integer
+      attribute :num_fonts_in_source, :integer
+
+      # Identity
+      attribute :family_name, :string
+      attribute :subfamily_name, :string
+      attribute :full_name, :string
+      attribute :postscript_name, :string
+      attribute :version, :string
+      attribute :font_revision, :float
+
+      # Style
+      attribute :weight_class, :integer
+      attribute :width_class, :integer
+      attribute :italic, Lutaml::Model::Type::Boolean
+      attribute :bold, Lutaml::Model::Type::Boolean
+      attribute :panose, :string
+      attribute :is_variable, Lutaml::Model::Type::Boolean
+      attribute :axes, AuditAxis, collection: true
+
+      # Coverage
+      attribute :total_codepoints, :integer
+      attribute :total_glyphs, :integer
+      attribute :cmap_subtables, :integer, collection: true
+      attribute :codepoints, :string, collection: true
+
+      # OpenType layout
+      attribute :opentype_scripts, :string, collection: true
+      attribute :features, :string, collection: true
+
+      json do
+        map "generated_at", to: :generated_at
+        map "fontisan_version", to: :fontisan_version
+        map "source_file", to: :source_file
+        map "source_sha256", to: :source_sha256
+        map "source_format", to: :source_format
+        map "font_index", to: :font_index
+        map "num_fonts_in_source", to: :num_fonts_in_source
+
+        map "family_name", to: :family_name
+        map "subfamily_name", to: :subfamily_name
+        map "full_name", to: :full_name
+        map "postscript_name", to: :postscript_name
+        map "version", to: :version
+        map "font_revision", to: :font_revision
+
+        map "weight_class", to: :weight_class
+        map "width_class", to: :width_class
+        map "italic", to: :italic
+        map "bold", to: :bold
+        map "panose", to: :panose
+        map "is_variable", to: :is_variable
+        map "axes", to: :axes
+
+        map "total_codepoints", to: :total_codepoints
+        map "total_glyphs", to: :total_glyphs
+        map "cmap_subtables", to: :cmap_subtables
+        map "codepoints", to: :codepoints
+
+        map "opentype_scripts", to: :opentype_scripts
+        map "features", to: :features
+      end
+
+      yaml do
+        map "generated_at", to: :generated_at
+        map "fontisan_version", to: :fontisan_version
+        map "source_file", to: :source_file
+        map "source_sha256", to: :source_sha256
+        map "source_format", to: :source_format
+        map "font_index", to: :font_index
+        map "num_fonts_in_source", to: :num_fonts_in_source
+
+        map "family_name", to: :family_name
+        map "subfamily_name", to: :subfamily_name
+        map "full_name", to: :full_name
+        map "postscript_name", to: :postscript_name
+        map "version", to: :version
+        map "font_revision", to: :font_revision
+
+        map "weight_class", to: :weight_class
+        map "width_class", to: :width_class
+        map "italic", to: :italic
+        map "bold", to: :bold
+        map "panose", to: :panose
+        map "is_variable", to: :is_variable
+        map "axes", to: :axes
+
+        map "total_codepoints", to: :total_codepoints
+        map "total_glyphs", to: :total_glyphs
+        map "cmap_subtables", to: :cmap_subtables
+        map "codepoints", to: :codepoints
+
+        map "opentype_scripts", to: :opentype_scripts
+        map "features", to: :features
+      end
+    end
+  end
+end

data/lib/fontisan/models.rb

@@ -6,6 +6,8 @@ module Fontisan
   module Models
     autoload :AllScriptsFeaturesInfo,
              "fontisan/models/all_scripts_features_info"
+    autoload :AuditAxis, "fontisan/models/audit_report"
+    autoload :AuditReport, "fontisan/models/audit_report"
     autoload :AxisInfo, "fontisan/models/variable_font_info"
     autoload :BitmapGlyph, "fontisan/models/bitmap_glyph"
     autoload :BitmapStrike, "fontisan/models/bitmap_strike"

data/lib/fontisan/type1/charstrings.rb

@@ -42,6 +42,39 @@ module Fontisan
       def initialize(private_dict = nil)
         @private_dict = private_dict || PrivateDict.new
         @charstrings = {}
+        @encoding_override = nil
+      end
+
+      # Build a CharStrings from a pre-built glyph-name → charstring-bytecode
+      # hash. Useful for constructing test fixtures without parsing a full
+      # Type 1 font. Optionally accepts +encoding:+ to override the default
+      # Adobe Standard Encoding (char code → glyph name).
+      #
+      # @param charstrings_hash [Hash{String=>String}]
+      # @param encoding [Hash{Integer=>String}, nil]
+      # @param private_dict [PrivateDict, nil]
+      # @return [CharStrings]
+      def self.from_hash(charstrings_hash, encoding: nil, private_dict: nil)
+        cs = new(private_dict)
+        charstrings_hash.each { |name, data| cs.register(name, data) }
+        cs.set_encoding(encoding) if encoding
+        cs
+      end
+
+      # Register (or replace) a glyph's charstring data.
+      #
+      # @param glyph_name [String]
+      # @param charstring_data [String] binary charstring bytecode
+      def register(glyph_name, charstring_data)
+        @charstrings[glyph_name] = charstring_data
+      end
+
+      # Override the default Adobe Standard Encoding with a custom
+      # +char_code → glyph_name+ map.
+      #
+      # @param encoding [Hash{Integer=>String}]
+      def set_encoding(encoding)
+        @encoding_override = encoding
       end
 
       # Parse CharStrings dictionary from decrypted Type 1 font data
@@ -72,7 +105,7 @@ module Fontisan
       #
       # @return [Hash] Character code to glyph name mapping
       def encoding
-        @encoding ||= build_standard_encoding
+        @encoding_override || (@encoding ||= build_standard_encoding)
       end
 
       # Iterate over all charstrings

data/lib/fontisan/type1/seac_expander.rb

@@ -2,6 +2,10 @@
 
 module Fontisan
   module Type1
+    # Error raised when a seac reference cannot be resolved (the referenced
+    # glyph is missing, or a cycle is detected in nested seac).
+    class SeacReferenceError < Fontisan::Error; end
+
     # Expands Type 1 seac composite glyphs into base + accent outlines
     #
     # [`SeacExpander`](lib/fontisan/type1/seac_expander.rb) handles the
@@ -9,6 +13,10 @@ module Fontisan
     # The seac operator combines two glyphs (a base character and an accent)
     # with a positioning offset, which must be decomposed for CFF conversion.
     #
+    # Supports nested seac: if a base or accent glyph is itself a seac
+    # composite, it is recursively expanded. Cycles are detected and raise
+    # {SeacReferenceError}.
+    #
     # The seac operator format is:
     # ```
     # seac asb adx ady bchar achar
@@ -28,6 +36,8 @@ module Fontisan
     #
     # @see https://www.adobe.com/devnet/font/pdfs/Type1.pdf
     class SeacExpander
+      MAX_DEPTH = 16
+
       # @return [CharStrings] Type 1 CharStrings dictionary
       attr_reader :charstrings
 
@@ -43,67 +53,15 @@ module Fontisan
         @private_dict = private_dict
       end
 
-      # Decompose a seac composite glyph into base + accent outlines
-      #
-      # This method:
-      # 1. Parses the seac operator to extract components
-      # 2. Gets CharStrings for base and accent glyphs
-      # 3. Parses both CharStrings into outline commands
-      # 4. Transforms the accent by (adx, ady) offset
-      # 5. Merges base and accent outlines into a single path
-      # 6. Returns the decomposed CharString data
+      # Decompose a seac composite glyph into base + accent outlines.
+      # Handles nested seac recursively.
       #
       # @param glyph_name [String] Name of the composite glyph to decompose
       # @return [String, nil] Decomposed CharString bytecode, or nil if not a seac composite
-      # @raise [Fontisan::Error] If base or accent glyphs are not found
-      #
-      # @example Decompose "Agrave" glyph
-      #   expander.decompose("Agrave")
+      # @raise [SeacReferenceError] If base or accent glyphs are not found,
+      #   or if a cycle is detected
       def decompose(glyph_name)
-        components = @charstrings.components_for(glyph_name)
-        return nil unless components
-
-        # Use the encoding map to lookup glyph names from character codes
-        base_glyph_name = @charstrings.encoding[components[:base]]
-        accent_glyph_name = @charstrings.encoding[components[:accent]]
-
-        if base_glyph_name.nil?
-          raise Fontisan::Error,
-                "Base glyph for char code #{components[:base]} not found"
-        end
-
-        if accent_glyph_name.nil?
-          raise Fontisan::Error,
-                "Accent glyph for char code #{components[:accent]} not found"
-        end
-
-        # Get CharStrings for base and accent
-        base_charstring = @charstrings[base_glyph_name]
-        accent_charstring = @charstrings[accent_glyph_name]
-
-        if base_charstring.nil?
-          raise Fontisan::Error,
-                "CharString not found for base glyph #{base_glyph_name}"
-        end
-
-        if accent_charstring.nil?
-          raise Fontisan::Error,
-                "CharString not found for accent glyph #{accent_glyph_name}"
-        end
-
-        # Parse both CharStrings into command sequences
-        base_commands = parse_charstring_to_commands(base_charstring)
-        accent_commands = parse_charstring_to_commands(accent_charstring)
-
-        # Transform accent by (adx, ady) offset
-        accent_commands = transform_commands(accent_commands, components[:adx],
-                                             components[:ady])
-
-        # Merge base and accent commands
-        merged_commands = merge_outline_commands(base_commands, accent_commands)
-
-        # Convert merged commands back to CharString bytecode
-        generate_charstring(merged_commands)
+        decompose_with_visited(glyph_name, Set.new)
       end
 
       # Check if a glyph is a seac composite
@@ -123,6 +81,59 @@ module Fontisan
 
       private
 
+      # Recursive decomposition with cycle detection via +visited+ set.
+      def decompose_with_visited(glyph_name, visited)
+        return nil unless composite?(glyph_name)
+
+        if visited.include?(glyph_name)
+          raise SeacReferenceError,
+                "Cycle detected in seac references: #{visited.to_a.join(' → ')} → #{glyph_name}"
+        end
+
+        if visited.size >= MAX_DEPTH
+          raise SeacReferenceError,
+                "seac nesting depth exceeds #{MAX_DEPTH} at #{glyph_name}"
+        end
+
+        visited_next = visited.dup.add(glyph_name)
+        components = @charstrings.components_for(glyph_name)
+
+        base_name = resolve_char_code(components[:base], "base", glyph_name)
+        accent_name = resolve_char_code(components[:accent], "accent", glyph_name)
+
+        base_commands = resolve_glyph_commands(base_name, visited_next)
+        accent_commands = resolve_glyph_commands(accent_name, visited_next)
+        accent_commands = transform_commands(accent_commands, components[:adx],
+                                             components[:ady])
+        merged = merge_outline_commands(base_commands, accent_commands)
+        generate_charstring(merged)
+      end
+
+      # Resolve a char code to a glyph name via the font's encoding.
+      def resolve_char_code(char_code, role, parent)
+        name = @charstrings.encoding[char_code]
+        return name if name
+
+        raise SeacReferenceError,
+              "#{role} glyph for char code #{char_code} (in #{parent}) not found in encoding"
+      end
+
+      # Get outline commands for a glyph, recursively expanding nested seac.
+      def resolve_glyph_commands(glyph_name, visited)
+        charstring = @charstrings[glyph_name]
+        if charstring.nil?
+          raise SeacReferenceError,
+                "CharString not found for glyph #{glyph_name}"
+        end
+
+        if composite?(glyph_name)
+          nested = decompose_with_visited(glyph_name, visited)
+          parse_charstring_to_commands(nested)
+        else
+          parse_charstring_to_commands(charstring)
+        end
+      end
+
       # Parse Type 1 CharString into drawing commands
       #
       # Converts Type 1 CharString bytecode into a list of drawing commands