ucode 0.1.0

data/lib/ucode/audit/extractors/color_capabilities.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "fontisan"
+
+module Ucode
+  module Audit
+    module Extractors
+      # Color-font capability summary: which color formats a face carries
+      # (COLR v0/v1, CPAL, SVG, CBDT/CBLC, sbix) plus lightweight counts
+      # from each table's header.
+      #
+      # Returned fields:
+      #   color_capabilities: Models::Audit::ColorCapabilities, or nil
+      #                       for Type 1
+      #
+      # Counts are best-effort — any table that fails to parse yields nil
+      # for its corresponding count fields rather than crashing the audit.
+      class ColorCapabilities < Base
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          font = context.font
+          return { color_capabilities: nil } unless sfnt?(font)
+
+          { color_capabilities: Models::Audit::ColorCapabilities.new(**gather(font)) }
+        end
+
+        private
+
+        def sfnt?(font)
+          font.is_a?(Fontisan::SfntFont)
+        end
+
+        def gather(font)
+          colr = colr_fields(font)
+          cpal = cpal_fields(font)
+          svg  = svg_fields(font)
+          cbdt = cbdt_fields(font)
+          sbix = sbix_fields(font)
+
+          formats = Models::Audit::ColorCapabilities.derive_formats(
+            has_colr: colr[:has_colr], colr_version: colr[:colr_version],
+            has_cpal: cpal[:has_cpal], has_svg: svg[:has_svg],
+            has_cbdt: cbdt[:has_cbdt], has_sbix: sbix[:has_sbix]
+          )
+
+          colr.merge(cpal).merge(svg).merge(cbdt).merge(sbix)
+            .merge(color_formats: formats)
+        end
+
+        def colr_fields(font)
+          return empty_colr unless font.has_table?("COLR")
+
+          colr = font.table("COLR")
+          return empty_colr unless colr
+
+          {
+            has_colr: true,
+            colr_version: colr.version&.to_i,
+            colr_base_glyph_count: colr.num_base_glyph_records&.to_i,
+            colr_layer_count: colr.num_layer_records&.to_i,
+          }
+        end
+
+        def empty_colr
+          { has_colr: false, colr_version: nil,
+            colr_base_glyph_count: nil, colr_layer_count: nil }
+        end
+
+        def cpal_fields(font)
+          return empty_cpal unless font.has_table?("CPAL")
+
+          cpal = font.table("CPAL")
+          return empty_cpal unless cpal
+
+          {
+            has_cpal: true,
+            cpal_palette_count: cpal.num_palettes&.to_i,
+            cpal_color_count: cpal.num_color_records&.to_i,
+          }
+        end
+
+        def empty_cpal
+          { has_cpal: false, cpal_palette_count: nil, cpal_color_count: nil }
+        end
+
+        def svg_fields(font)
+          return empty_svg unless font.has_table?("SVG ")
+
+          svg = font.table("SVG ")
+          return empty_svg unless svg
+
+          {
+            has_svg: true,
+            svg_document_count: svg.num_svg_documents&.to_i,
+          }
+        end
+
+        def empty_svg
+          { has_svg: false, svg_document_count: nil }
+        end
+
+        # CBDT/CBLC are paired tables: CBLC holds the strike index,
+        # CBDT holds the bitmap data. has_cbdt vs has_cblc disagreement
+        # is reported as-is — audit consumers can spot the inconsistency.
+        def cbdt_fields(font)
+          has_cbdt = font.has_table?("CBDT")
+          has_cblc = font.has_table?("CBLC")
+          strike_count = cblc_strike_count(font) if has_cblc
+
+          {
+            has_cbdt: has_cbdt,
+            has_cblc: has_cblc,
+            cbdt_strike_count: strike_count,
+          }
+        end
+
+        def cblc_strike_count(font)
+          cblc = font.table("CBLC")
+          return nil unless cblc
+
+          cblc.num_sizes&.to_i
+        end
+
+        def sbix_fields(font)
+          return empty_sbix unless font.has_table?("sbix")
+
+          sbix = font.table("sbix")
+          return empty_sbix unless sbix
+
+          {
+            has_sbix: true,
+            sbix_strike_count: sbix.num_strikes&.to_i,
+          }
+        end
+
+        def empty_sbix
+          { has_sbix: false, sbix_strike_count: nil }
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/extractors/coverage.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Audit
+    module Extractors
+      # Coverage fields: how many codepoints and glyphs the font ships,
+      # the compact codepoint-range view (default), and the optional flat
+      # per-codepoint list (only when `--all-codepoints` is on).
+      #
+      # Returned fields:
+      #   total_codepoints, total_glyphs, cmap_subtables,
+      #   codepoint_ranges, codepoints
+      #
+      # ucode delta vs fontisan: the `codepoints` field uses "U+XXXX"
+      # string form per `02-audit-schema-design.md`. Does NOT emit
+      # aggregations (blocks/scripts) — that's the Aggregations
+      # extractor in TODO 10. Coverage only emits the raw codepoint set.
+      class Coverage < Base
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          font = context.font
+          codepoints = context.codepoints
+          {
+            total_codepoints: codepoints.length,
+            total_glyphs: total_glyphs(font),
+            cmap_subtables: cmap_subtable_formats(font),
+            codepoint_ranges: CodepointRangeCoalescer.call(codepoints),
+            codepoints: codepoints_for_report(context, codepoints),
+          }
+        end
+
+        private
+
+        def total_glyphs(font)
+          return nil unless font.has_table?("maxp")
+
+          font.table("maxp").num_glyphs
+        end
+
+        def cmap_subtable_formats(font)
+          return [] unless font.has_table?("cmap")
+
+          font.table("cmap").subtable_formats
+        end
+
+        def codepoints_for_report(context, codepoints)
+          return [] unless context.all_codepoints?
+
+          codepoints.map { |cp| format("U+%<cp>04X", cp: cp) }
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/extractors/hinting.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+require "fontisan"
+
+module Ucode
+  module Audit
+    module Extractors
+      # Hinting summary: TrueType bytecode counts + gasp policy + CFF stem
+      # count, with derived `is_unhinted` and `hinting_format` fields.
+      #
+      # Returned fields:
+      #   hinting: Models::Audit::Hinting instance, or nil for Type 1
+      #
+      # The fpgm/prep/cvt/gasp tables have no BinData classes yet — they
+      # are read as raw bytes from `font.table_data`. Bytecode is one
+      # byte per instruction; cvt is an array of FWord (int16), so the
+      # entry count is bytesize / 2.
+      class Hinting < Base
+        # Raw CFF / CFF2 charstring operator bytes that declare stem hints.
+        HSTEM    = 1
+        VSTEM    = 3
+        HSTEMHM  = 18
+        VSTEMHM  = 23
+        HINTMASK = 19
+        CNTRMASK = 20
+
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          font = context.font
+          return { hinting: nil } unless sfnt?(font)
+
+          { hinting: Models::Audit::Hinting.new(**gather(font)) }
+        end
+
+        private
+
+        def sfnt?(font)
+          font.is_a?(Fontisan::SfntFont)
+        end
+
+        def gather(font)
+          tt = truetype_fields(font)
+          cff = cff_fields(font)
+          gasp = parse_gasp(font)
+
+          derived = Models::Audit::Hinting.derive_flags(
+            has_tt: tt[:has_fpgm] || tt[:has_prep] || tt[:has_cvt],
+            has_cff: cff[:cff_has_private_dict],
+            has_gasp: !gasp.empty?,
+          )
+
+          tt.merge(cff).merge(gasp_ranges: gasp).merge(derived)
+        end
+
+        def truetype_fields(font)
+          {
+            has_fpgm: font.has_table?("fpgm"),
+            fpgm_instruction_count: byte_count(font, "fpgm"),
+            has_prep: font.has_table?("prep"),
+            prep_instruction_count: byte_count(font, "prep"),
+            has_cvt: font.has_table?("cvt"),
+            cvt_entry_count: cvt_entry_count(font),
+            has_cvar: font.has_table?("cvar"),
+          }
+        end
+
+        def cff_fields(font)
+          has_cff1 = font.has_table?("CFF ")
+          has_cff2 = font.has_table?("CFF2")
+          has_private = has_cff1 || has_cff2
+
+          {
+            cff_has_private_dict: has_private,
+            cff_hint_count: has_cff1 ? count_cff_stems(font) : nil,
+          }
+        end
+
+        def byte_count(font, tag)
+          return nil unless font.has_table?(tag)
+
+          font.table_data[tag]&.bytesize
+        end
+
+        def cvt_entry_count(font)
+          return nil unless font.has_table?("cvt")
+
+          bytes = font.table_data["cvt"]
+          return nil unless bytes
+
+          bytes.bytesize / 2
+        end
+
+        # Parse the gasp table from raw bytes. Format: uint16 version,
+        # uint16 numRanges, then numRanges × (uint16 rangeMaxPPEM,
+        # uint16 rangeFlags). Returns [] if gasp is absent or truncated.
+        def parse_gasp(font)
+          return [] unless font.has_table?("gasp")
+
+          data = font.table_data["gasp"]
+          return [] unless data && data.bytesize >= 4
+
+          _version, num_ranges = data.unpack("nn")
+          ranges = []
+          offset = 4
+          num_ranges.times do
+            break if offset + 4 > data.bytesize
+
+            max_ppem, flags = data[offset, 4].unpack("nn")
+            ranges << Models::Audit::GaspRange.from_flags(max_ppem, flags)
+            offset += 4
+          end
+          ranges
+        end
+
+        def count_cff_stems(font)
+          return nil unless font.has_table?("CFF ")
+
+          cff = font.table("CFF ")
+          return nil unless cff
+
+          index = cff.charstrings_index(0)
+          return nil unless index
+
+          total = 0
+          index.count.times do |glyph_index|
+            data = index[glyph_index]
+            next unless data
+
+            total += count_stems_in_charstring(data)
+          end
+          total
+        rescue Fontisan::CorruptedTableError
+          nil
+        end
+
+        # Lightweight Type-2 CharString scanner that counts stem hints
+        # without instantiating a full CharString (which needs a Private
+        # DICT, global/local subrs, etc.). Operates purely on bytes.
+        def count_stems_in_charstring(data)
+          io = StringIO.new(data)
+          stack = 0
+          stems = 0
+
+          until io.eof?
+            byte = io.getbyte
+            next if byte.nil?
+
+            stack, stems = process_byte(io, byte, stack, stems)
+          end
+
+          stems
+        end
+
+        def process_byte(io, byte, stack, stems)
+          if operator_byte?(byte)
+            apply_operator(io, byte, stack, stems)
+          else
+            [consume_operand(io, byte, stack), stems]
+          end
+        end
+
+        def operator_byte?(byte)
+          byte <= 31 && byte != 28
+        end
+
+        def apply_operator(io, byte, stack, stems)
+          case byte
+          when 12
+            io.getbyte
+            [0, stems]
+          when HSTEM, VSTEM, HSTEMHM, VSTEMHM
+            [0, stems + stack / 2]
+          when HINTMASK, CNTRMASK
+            new_stems = stems + stack / 2
+            io.read((new_stems + 7) / 8)
+            [0, new_stems]
+          else
+            [0, stems]
+          end
+        end
+
+        def consume_operand(io, byte, stack)
+          case byte
+          when 28
+            io.read(2)
+          when 255
+            io.read(4)
+          when 247..254
+            io.getbyte
+          end
+          stack + 1
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/extractors/identity.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "fontisan"
+
+module Ucode
+  module Audit
+    module Extractors
+      # Identity fields: the human-readable names a font uses to describe
+      # itself, drawn from the `name` table (SFNT) or font dictionary
+      # (Type 1).
+      #
+      # Returned fields:
+      #   family_name, subfamily_name, full_name, postscript_name,
+      #   version, font_revision
+      class Identity < Base
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          font = context.font
+          if font.is_a?(Fontisan::Type1Font)
+            type1_identity(font)
+          else
+            sfnt_identity(font)
+          end
+        end
+
+        private
+
+        def sfnt_identity(font)
+          name_table = table(font, "name")
+          head_table = table(font, "head")
+
+          {
+            family_name: english_name(name_table, Fontisan::Tables::Name::FAMILY),
+            subfamily_name: english_name(name_table, Fontisan::Tables::Name::SUBFAMILY),
+            full_name: english_name(name_table, Fontisan::Tables::Name::FULL_NAME),
+            postscript_name: english_name(name_table, Fontisan::Tables::Name::POSTSCRIPT_NAME),
+            version: english_name(name_table, Fontisan::Tables::Name::VERSION),
+            font_revision: head_table&.font_revision,
+          }
+        end
+
+        def type1_identity(font)
+          font_info = font.font_dictionary&.font_info
+          {
+            family_name: font_info&.family_name,
+            subfamily_name: nil,
+            full_name: font_info&.full_name,
+            postscript_name: font.font_name,
+            version: font_info&.version,
+            font_revision: nil,
+          }
+        end
+
+        def table(font, tag)
+          font.table(tag) if font.has_table?(tag)
+        end
+
+        def english_name(name_table, name_id)
+          name_table&.english_name(name_id)
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/extractors/licensing.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "fontisan"
+
+module Ucode
+  module Audit
+    module Extractors
+      # Licensing + embedding permissions + vendor provenance.
+      #
+      # Returned fields:
+      #   licensing: Models::Audit::Licensing instance, or nil for Type 1
+      #
+      # Type 1 fonts have no OS/2 table; their licensing is nil. WOFF/
+      # WOFF2 carry the same OS/2 + name tables as TTF/OTF and need no
+      # special handling.
+      class Licensing < Base
+        # nameID → AuditReport field name, per OpenType name table spec.
+        NAME_IDS = {
+          copyright: 0,
+          trademark: 7,
+          manufacturer: 8,
+          designer: 9,
+          description: 10,
+          vendor_url: 11,
+          designer_url: 12,
+          license_description: 13,
+          license_url: 14,
+        }.freeze
+        private_constant :NAME_IDS
+
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          font = context.font
+          return { licensing: nil } unless sfnt?(font)
+
+          os2 = table(font, "OS/2")
+          name = table(font, "name")
+
+          {
+            licensing: Models::Audit::Licensing.new(
+              **name_fields(name),
+              vendor_id: sanitized_vendor_id(os2),
+              embedding_type: Models::Audit::EmbeddingType.decode(os2&.fs_type&.to_i),
+              fs_selection_flags: Models::Audit::FsSelectionFlags.decode(os2&.fs_selection&.to_i),
+            ),
+          }
+        end
+
+        private
+
+        def sfnt?(font)
+          font.is_a?(Fontisan::SfntFont)
+        end
+
+        def table(font, tag)
+          font.table(tag) if font.has_table?(tag)
+        end
+
+        def name_fields(name)
+          return {} unless name
+
+          NAME_IDS.transform_values { |id| name.english_name(id) }
+        end
+
+        def sanitized_vendor_id(os2)
+          raw = os2&.ach_vend_id
+          return nil if raw.nil?
+
+          raw.gsub(/[\x00\s]+$/, "")
+        end
+      end
+    end
+  end
+end

data/lib/ucode/audit/extractors/metrics.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "fontisan"
+
+module Ucode
+  module Audit
+    module Extractors
+      # Layout-critical metrics consolidated from head, hhea, OS/2, post.
+      #
+      # Returned fields:
+      #   metrics: Models::Audit::Metrics instance, or nil for Type 1
+      #
+      # All table reads are nil-safe; tables may be absent in stripped
+      # WOFF builds or legacy formats.
+      class Metrics < Base
+        # @param context [Ucode::Audit::Context]
+        # @return [Hash{Symbol=>Object}]
+        def extract(context)
+          font = context.font
+          return { metrics: nil } unless sfnt?(font)
+
+          { metrics: Models::Audit::Metrics.new(**gather(font)) }
+        end
+
+        private
+
+        def sfnt?(font)
+          font.is_a?(Fontisan::SfntFont)
+        end
+
+        def gather(font)
+          head_fields(font)
+            .merge(hhea_fields(font))
+            .merge(os2_fields(font))
+            .merge(post_fields(font))
+        end
+
+        def head_fields(font)
+          head = table(font, "head")
+          return {} unless head
+
+          {
+            units_per_em: head.units_per_em&.to_i,
+            bbox_x_min: head.x_min&.to_i,
+            bbox_y_min: head.y_min&.to_i,
+            bbox_x_max: head.x_max&.to_i,
+            bbox_y_max: head.y_max&.to_i,
+          }
+        end
+
+        def hhea_fields(font)
+          hhea = table(font, "hhea")
+          return {} unless hhea
+
+          {
+            hhea_ascent: hhea.ascent&.to_i,
+            hhea_descent: hhea.descent&.to_i,
+            hhea_line_gap: hhea.line_gap&.to_i,
+          }
+        end
+
+        # OS/2 table fields exposed on Metrics, as
+        #   `Metrics attribute name` => `OS/2 reader method`.
+        OS2_FIELDS = {
+          typo_ascender: :s_typo_ascender,
+          typo_descender: :s_typo_descender,
+          typo_line_gap: :s_typo_line_gap,
+          win_ascent: :us_win_ascent,
+          win_descent: :us_win_descent,
+          x_height: :sx_height,
+          cap_height: :s_cap_height,
+          subscript_x_size: :y_subscript_x_size,
+          subscript_y_size: :y_subscript_y_size,
+          subscript_x_offset: :y_subscript_x_offset,
+          subscript_y_offset: :y_subscript_y_offset,
+          superscript_x_size: :y_superscript_x_size,
+          superscript_y_size: :y_superscript_y_size,
+          superscript_x_offset: :y_superscript_x_offset,
+          superscript_y_offset: :y_superscript_y_offset,
+          strikeout_size: :y_strikeout_size,
+          strikeout_position: :y_strikeout_position,
+        }.freeze
+        private_constant :OS2_FIELDS
+
+        def os2_fields(font)
+          os2 = table(font, "OS/2")
+          return {} unless os2
+
+          OS2_FIELDS.transform_values { |reader| os2.public_send(reader)&.to_i }
+        end
+
+        def post_fields(font)
+          post = table(font, "post")
+          return {} unless post
+
+          {
+            underline_position: post.underline_position&.to_f,
+            underline_thickness: post.underline_thickness&.to_f,
+          }
+        end
+
+        def table(font, tag)
+          font.table(tag) if font.has_table?(tag)
+        end
+      end
+    end
+  end
+end