arrolio 0.1.0

data/lib/arrolio/harness/text_extractor.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Arrolio
+  module Harness
+    # Extracts text from PDF files for diff/matching. Uses poppler's
+    # +pdftotext+ as the primary backend (reliable with CIDFont
+    # subsets); falls back to returning an empty string if the
+    # tool is unavailable.
+    class TextExtractor
+      attr_reader :path
+
+      def initialize(path)
+        @path = path.to_s
+      end
+
+      # Returns an Array of Strings — one per page. Uses +pdftotext+
+      # in raw mode (no layout reconstruction) for maximum text
+      # recovery. For layout-aware extraction, pass +layout: true+.
+      def pages(layout: false)
+        return [] unless pdftotext_available?
+
+        args = ['pdftotext']
+        args << '-layout' if layout
+        args << '-q' << @path << '-'
+        stdout, _stderr, status = Open3.capture3(*args)
+        return [] unless status.success?
+
+        text = stdout.force_encoding('UTF-8').scrub
+        split_by_page(text)
+      end
+
+      # Returns all text as a single String (pages joined by "\f").
+      def full_text(layout: false)
+        pages(layout: layout).join("\f")
+      end
+
+      # Word count across all pages.
+      def word_count
+        pages.sum { |text| text.split.length }
+      end
+
+      private
+
+      def pdftotext_available?
+        _, _, status = Open3.capture3('which', 'pdftotext')
+        status.success?
+      end
+
+      def split_by_page(text)
+        return [text] unless text.include?("\f")
+
+        text.split("\f", -1)
+      end
+    end
+  end
+end

data/lib/arrolio/harness.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Harness
+    autoload :PdfDiff, 'arrolio/harness/pdf_diff'
+    autoload :TextDiff, 'arrolio/harness/text_diff'
+    autoload :TextExtractor, 'arrolio/harness/text_extractor'
+    autoload :PixelDiff, 'arrolio/harness/pixel_diff'
+  end
+end

data/lib/arrolio/inline_run.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # One inline run within a paragraph: a contiguous span of text
+  # sharing a single Style. A paragraph is laid out as a list of
+  # InlineRun instances. Lives at the Layout level so that other
+  # Layout modules (InlineBuilder, TextLayout, FO::Compiler) all
+  # share the same type.
+  #
+  # Carries optional baseline_shift (:sub / :sup / nil) and
+  # font_size_scale for subscript/superscript rendering, plus
+  # optional href for hyperlink annotations.
+  class InlineRun
+    attr_reader :text, :style, :baseline_shift, :font_size_scale, :href
+
+    def initialize(text, style: Style.new, baseline_shift: nil,
+                   font_size_scale: 1.0, href: nil)
+      @text = text.to_s
+      @style = style
+      @baseline_shift = baseline_shift
+      @font_size_scale = font_size_scale.to_f
+      @href = href
+    end
+
+    def empty?
+      @text.empty?
+    end
+
+    def length
+      @text.length
+    end
+
+    def width(measurer, font_size: style.font_size)
+      measurer.width_of_run(
+        @text,
+        font_size: font_size * @font_size_scale,
+        character_spacing: style.character_spacing,
+        word_spacing: style.word_spacing
+      )
+    end
+
+    def hyperlink?
+      !@href.nil? && !@href.empty?
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        text == other.text &&
+        style == other.style &&
+        baseline_shift == other.baseline_shift &&
+        font_size_scale == other.font_size_scale &&
+        href == other.href
+    end
+
+    def hash
+      [text, style, baseline_shift, font_size_scale, href].hash
+    end
+  end
+end

data/lib/arrolio/layout_spec/flow.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Arrolio
+  class LayoutSpec
+    # Declares a named content flow into a region. Declarative
+    # only — Engine::Paged takes a flat Flowable list and a body
+    # template today.
+    Flow = Struct.new(:name, :region, :source, :default_style_id,
+                      keyword_init: true) do
+      def initialize(*)
+        super
+        self.name = self.name.to_sym if self.name
+        freeze
+      end
+    end
+  end
+end

data/lib/arrolio/layout_spec/loader.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Arrolio
+  class LayoutSpec
+    # Loads a LayoutSpec from YAML. Lengths accept mm/cm/in/pt/px.
+    module Loader
+      MM_TO_PT = 2.83464567
+      CM_TO_PT = 28.3464567
+      IN_TO_PT = 72.0
+      PT_TO_PT = 1.0
+      PX_TO_PT = 0.75
+
+      module_function
+
+      def load(source)
+        build_from_hash(read_yaml(source))
+      end
+
+      def read_yaml(source)
+        case source
+        when Hash then source
+        when String
+          if File.exist?(source)
+            result = YAML.safe_load_file(source, aliases: true)
+            result.is_a?(Hash) ? result : {}
+          else
+            result = YAML.safe_load(source, aliases: true)
+            result.is_a?(Hash) ? result : {}
+          end
+        when IO, StringIO
+          result = YAML.safe_load(source.read, aliases: true)
+          result.is_a?(Hash) ? result : {}
+        else
+          raise ArgumentError, "Loader needs Hash/String/IO; got #{source.class}"
+        end
+      end
+
+      def build_from_hash(hash)
+        templates = build_templates(hash.fetch('page_templates', {}))
+        default = hash.fetch('default_page_template') do
+          templates.keys.first or
+            raise LayoutSpecError, 'no page templates in layout spec', spec_field: :page_templates
+        end
+        styles = Style::Registry.new(hash.fetch('styles', {}))
+        flows = hash.fetch('flows', {}).transform_values do |f|
+          f = { 'region' => f } unless f.is_a?(Hash)
+          Flow.new(
+            name: f['name'],
+            region: f['region']&.to_sym,
+            source: f['source'],
+            default_style_id: f['default_style_id']&.to_sym
+          )
+        end
+        LayoutSpec.new(
+          page_templates: templates,
+          default_page_template: default,
+          styles: styles,
+          flows: flows,
+          font_paths: hash.fetch('font_paths', {}),
+          header_footer: hash.fetch('header_footer', {}),
+          cover_logo: hash.fetch('cover_logo', {}),
+          font_manifest: hash.fetch('font_manifest', {})
+        )
+      end
+
+      def build_templates(hash)
+        hash.to_h do |name, attrs|
+          attrs = {} unless attrs.is_a?(Hash)
+          [name, build_template(name, attrs)]
+        end
+      end
+
+      def build_template(name, attrs)
+        PageTemplate.new(
+          name: name,
+          page_size: attrs['page_size'] || PageTemplate::LETTER,
+          margins: build_margins(attrs),
+          region_extents: build_region_extents(attrs.fetch('region_extents', {}))
+        )
+      end
+
+      def build_margins(attrs)
+        margins = attrs['margins']
+        return PageTemplate::LETTER.first if margins.nil?
+
+        case margins
+        when Numeric, String then { all: parse_length(margins) }
+        when Hash
+          margins.to_h { |k, v| [k.to_sym, parse_length(v)] }
+        else
+          raise LayoutSpecError, 'margins must be number/string/hash', spec_field: :margins
+        end
+      end
+
+      def build_region_extents(hash)
+        hash.to_h { |k, v| [k.to_sym, parse_length(v)] }
+      end
+
+      def parse_length(value)
+        return value.to_f if value.is_a?(Numeric)
+
+        case value.to_s
+        when /\A([\d.]+)mm\z/ then Regexp.last_match(1).to_f * MM_TO_PT
+        when /\A([\d.]+)cm\z/ then Regexp.last_match(1).to_f * CM_TO_PT
+        when /\A([\d.]+)in\z/ then Regexp.last_match(1).to_f * IN_TO_PT
+        when /\A([\d.]+)px\z/ then Regexp.last_match(1).to_f * PX_TO_PT
+        when /\A([\d.]+)pt\z/ then Regexp.last_match(1).to_f * PT_TO_PT
+        when /\A[\d.]+\z/ then value.to_f
+        else
+          raise LayoutSpecError, "cannot parse length #{value.inspect}", spec_field: :length
+        end
+      end
+    end
+  end
+end

data/lib/arrolio/layout_spec/page_template.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Arrolio
+  class LayoutSpec
+    # Page geometry template ("fo:simple-page-master" in XSL-FO).
+    # Coordinates are PDF-default user space: origin at the
+    # bottom-left of the page, +y+ grows upward. Region +y+ is the
+    # bottom edge of the region.
+    class PageTemplate
+      LETTER = [612.0, 792.0].freeze
+      A4 = [595.276, 841.89].freeze
+
+      attr_reader :name, :page_size, :margins, :region_extents, :regions
+
+      def initialize(name:, page_size: LETTER, margins: 72, region_extents: {})
+        @name = name.to_sym
+        @page_size = resolve_page_size(page_size)
+        @margins = normalise_margins(margins)
+        @region_extents = default_region_extents.merge(region_extents.to_h)
+        @regions = compute_regions.freeze
+        freeze
+      end
+
+      def body_region
+        @regions[:body]
+      end
+
+      def region(name)
+        @regions[name.to_sym]
+      end
+
+      def width
+        @page_size[0]
+      end
+
+      def height
+        @page_size[1]
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          name == other.name &&
+          page_size == other.page_size &&
+          margins == other.margins &&
+          region_extents == other.region_extents
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, name, page_size, margins, region_extents].hash
+      end
+
+      private
+
+      def resolve_page_size(spec)
+        case spec
+        when Symbol, String
+          constant = spec.to_s.upcase.to_sym
+          self.class.const_defined?(constant, false) ? self.class.const_get(constant) : LETTER
+        when Array
+          [spec[0].to_f, spec[1].to_f]
+        else
+          LETTER
+        end
+      end
+
+      def normalise_margins(m)
+        case m
+        when Numeric
+          { top: m.to_f, right: m.to_f, bottom: m.to_f, left: m.to_f }
+        when Hash
+          base = m.transform_keys(&:to_sym)
+          all = base[:all]
+          {
+            top: base[:top] || all || 72.0,
+            right: base[:right] || all || 72.0,
+            bottom: base[:bottom] || all || 72.0,
+            left: base[:left] || all || 72.0
+          }
+        else
+          { top: 72.0, right: 72.0, bottom: 72.0, left: 72.0 }
+        end
+      end
+
+      def default_region_extents
+        { before: 0.0, after: 0.0, start: 0.0, end: 0.0 }
+      end
+
+      def compute_regions
+        pw = width
+        ph = height
+        m = @margins
+        e = @region_extents
+        inner_w = pw - m[:left] - m[:right] - e[:start] - e[:end]
+        inner_h = ph - m[:top] - m[:bottom] - e[:before] - e[:after]
+        {
+          body: Region.new(name: :body,
+                           x: m[:left] + e[:start],
+                           y: m[:bottom] + e[:after],
+                           width: inner_w,
+                           height: inner_h),
+          before: Region.new(name: :before,
+                             x: m[:left] + e[:start],
+                             y: ph - m[:top] - e[:before],
+                             width: inner_w,
+                             height: e[:before]),
+          after: Region.new(name: :after,
+                            x: m[:left] + e[:start],
+                            y: m[:bottom],
+                            width: inner_w,
+                            height: e[:after]),
+          start: Region.new(name: :start,
+                            x: m[:left],
+                            y: m[:bottom] + e[:after],
+                            width: e[:start],
+                            height: inner_h),
+          end: Region.new(name: :end,
+                          x: pw - m[:right] - e[:end],
+                          y: m[:bottom] + e[:after],
+                          width: e[:end],
+                          height: inner_h)
+        }
+      end
+    end
+  end
+end

data/lib/arrolio/layout_spec/page_template_selector.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Arrolio
+  class LayoutSpec
+    # Selects the appropriate page template based on page parity
+    # (odd/even) and the configured template set. Supports three
+    # modes:
+    #   - Single template (current behavior): always returns the
+    #     same template for every page.
+    #   - Odd/even templates: returns different templates for odd
+    #     vs even pages, typically mirroring the inner/outer margins
+    #     for double-sided printing.
+    #   - Custom mapping: caller provides a proc or hash mapping
+    #     page numbers to template names.
+    class PageTemplateSelector
+      attr_reader :default_template, :odd_template, :even_template
+
+      # +default_template:+ template name used when no odd/even
+      #   templates are configured.
+      # +odd_template:+ template name for odd pages (1, 3, 5, ...).
+      # +even_template:+ template name for even pages (2, 4, 6, ...).
+      def initialize(default_template:, odd_template: nil, even_template: nil)
+        @default_template = default_template.to_sym
+        @odd_template = odd_template&.to_sym
+        @even_template = even_template&.to_sym
+        freeze
+      end
+
+      # Returns the template name for the given page number.
+      def name_for(page_number)
+        return @default_template unless @odd_template || @even_template
+
+        if page_number.odd?
+  (@odd_template || @default_template)
+else
+  (@even_template || @default_template)
+end
+      end
+
+      # Does this selector use different templates for odd/even?
+      def alternating?
+        !(@odd_template.nil? && @even_template.nil?)
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          default_template == other.default_template &&
+          odd_template == other.odd_template &&
+          even_template == other.even_template
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, default_template, odd_template, even_template].hash
+      end
+    end
+  end
+end

data/lib/arrolio/layout_spec/region.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Arrolio
+  class LayoutSpec
+    # Named rectangle within a PageTemplate. The five standard
+    # regions are +:body+, +:before+ (header), +:after+ (footer),
+    # +:start+ (left), +:end+ (right). Pure geometry; runtime
+    # consumed state lives in Frame.
+    class Region
+      attr_reader :name, :x, :y, :width, :height
+
+      def initialize(name:, x:, y:, width:, height:)
+        @name = name.to_sym
+        @x = x.to_f
+        @y = y.to_f
+        @width = width.to_f
+        @height = height.to_f
+        freeze
+      end
+
+      def area
+        @width * @height
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          name == other.name && x == other.x && y == other.y &&
+          width == other.width && height == other.height
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, name, x, y, width, height].hash
+      end
+    end
+  end
+end

data/lib/arrolio/layout_spec/scale_length.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Arrolio
+  class LayoutSpec
+    class ScaleLength
+      attr_reader :base_value, :scale_factor
+
+      def initialize(base_value:, scale_factor: 1.0)
+        @base_value = base_value.to_f
+        @scale_factor = scale_factor.to_f
+        freeze
+      end
+
+      def resolved
+        @base_value * @scale_factor
+      end
+
+      def with_scale(factor)
+        self.class.new(base_value: @base_value, scale_factor: factor)
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          base_value == other.base_value &&
+          scale_factor == other.scale_factor
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, base_value, scale_factor].hash
+      end
+    end
+  end
+end

data/lib/arrolio/layout_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Arrolio::LayoutSpec — typed layout description, YAML-loadable.
+module Arrolio
+  class LayoutSpec
+    autoload :PageTemplate, 'arrolio/layout_spec/page_template'
+    autoload :PageTemplateSelector, 'arrolio/layout_spec/page_template_selector'
+    autoload :ScaleLength, 'arrolio/layout_spec/scale_length'
+    autoload :Region, 'arrolio/layout_spec/region'
+    autoload :Flow, 'arrolio/layout_spec/flow'
+    autoload :Loader, 'arrolio/layout_spec/loader'
+
+    attr_reader :page_templates, :default_page_template, :styles, :flows,
+                :font_paths, :header_footer_config, :cover_logo_config,
+                :font_manifest_config
+
+    def initialize(page_templates:, default_page_template:,
+                   styles:, flows: {}, font_paths: {},
+                   header_footer: {}, cover_logo: {}, font_manifest: {})
+      @font_paths = font_paths.transform_keys(&:to_s).freeze
+      @page_templates = page_templates.transform_keys(&:to_sym).freeze
+      @default_page_template = default_page_template.to_sym
+      @styles = styles
+      @flows = flows.transform_keys(&:to_sym).freeze
+      @header_footer_config = (header_footer || {}).freeze
+      @cover_logo_config = (cover_logo || {}).freeze
+      @font_manifest_config = (font_manifest || {}).freeze
+      validate!
+      freeze
+    end
+
+    def page_template(name = nil)
+      key = (name || @default_page_template).to_sym
+      @page_templates[key] ||
+        (raise LayoutSpecError,
+               "Unknown page template #{key.inspect}; have: #{@page_templates.keys.inspect}",
+               spec_field: :page_template)
+    end
+
+    def resolve_style(name, fallback: nil)
+      @styles.resolve(name, fallback: fallback || Style::Definition.new)
+    end
+
+    def flow(name)
+      @flows[name.to_sym]
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        page_templates == other.page_templates &&
+        default_page_template == other.default_page_template &&
+        styles == other.styles &&
+        flows == other.flows &&
+        header_footer_config == other.header_footer_config &&
+        cover_logo_config == other.cover_logo_config &&
+        font_manifest_config == other.font_manifest_config
+    end
+
+    alias eql? ==
+
+    def hash
+      [self.class, page_templates, default_page_template, styles, flows,
+       header_footer_config, cover_logo_config, font_manifest_config].hash
+    end
+
+    private
+
+    def validate!
+      unless @page_templates.key?(@default_page_template)
+        raise LayoutSpecError,
+              "Default page template #{@default_page_template.inspect} is not in page_templates",
+              spec_field: :default_page_template
+      end
+
+      unless @styles.is_a?(Style::Registry)
+        raise LayoutSpecError,
+              "styles must be a Style::Registry (got #{@styles.class})",
+              spec_field: :styles
+      end
+
+      @page_templates.each do |name, tpl|
+        next if tpl.is_a?(PageTemplate)
+
+        raise LayoutSpecError,
+              "page_templates[#{name.inspect}] must be a PageTemplate",
+              spec_field: :page_templates
+      end
+    end
+  end
+end

data/lib/arrolio/logger.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # Structured logging facade. Replaces scattered +warn+ calls with
+  # level-filtered, silencable output. Default level +:warn+ keeps
+  # production rendering quiet; set +Arrolio::Logger.level = :debug+
+  # or +ARROOLIO_LOG_LEVEL=debug+ to restore tracing during development.
+  class Logger
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+    DEFAULT_LEVEL = :warn
+
+    @level = LEVELS.fetch(DEFAULT_LEVEL)
+    @target = $stderr
+
+    class << self
+      attr_accessor :target
+      attr_reader :level
+
+      def level=(name)
+        @level = LEVELS.fetch(name.to_sym) { LEVELS.fetch(DEFAULT_LEVEL) }
+      end
+
+      def level_name
+        LEVELS.key(@level) || DEFAULT_LEVEL
+      end
+
+      LEVELS.each_key do |name|
+        define_method(name) do |msg|
+          emit(name, msg)
+        end
+      end
+
+      # Reset to defaults — used by specs and between pipeline runs.
+      def reset!
+        @level = LEVELS.fetch(DEFAULT_LEVEL)
+        @target = $stderr
+      end
+
+      private
+
+      def emit(level_name, msg)
+        threshold = LEVELS.fetch(level_name)
+        return if threshold < @level
+
+        @target.puts "[#{level_name}] #{msg}"
+      end
+    end
+
+    # Pick up the env var on first load. Allows
+    # +ARROOLIO_LOG_LEVEL=debug bundle exec rake+ without code changes.
+    env_level = ENV['ARROOLIO_LOG_LEVEL'].to_s.strip
+    self.level = env_level unless env_level.empty?
+  end
+end