export_kit 0.1.0

data/lib/export_kit/renderers/base.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ExportKit
+  module Renderers
+    class TooLarge < StandardError; end
+
+    class InvalidDocument < StandardError
+      attr_reader :error_details
+
+      def initialize(message = "invalid export data", error_details: {})
+        super(message)
+        @error_details = Result.failure(:invalid, error_details:).error_details
+      end
+
+      def at(**details)
+        self.class.new(error_details: details.merge(error_details))
+      end
+    end
+
+    # Shared validation for every renderer: rows must match their declared columns and contain
+    # only format-neutral scalar values (or arrays of scalars).
+    class Base
+      SCALARS = [String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
+
+      def self.validate_row!(record_set, row)
+        column = invalid_column(record_set, row)
+        valid = row.is_a?(Hash) && row.keys == record_set.columns && row.values.all? { plain?(it) }
+        return if valid
+
+        raise InvalidDocument.new(error_details: { record_set: record_set.name, column: })
+      end
+
+      def self.invalid_column(record_set, row)
+        return unless row.is_a?(Hash)
+
+        record_set.columns.find { !row.key?(it) || !plain?(row[it]) }
+      end
+
+      def self.plain?(value)
+        return value.all? { scalar?(it) } if value.is_a?(Array)
+
+        scalar?(value)
+      end
+
+      def self.scalar?(value)
+        return value.finite? if value.is_a?(Float)
+        return valid_string?(value) if value.is_a?(String)
+
+        SCALARS.any? { value.is_a?(it) }
+      end
+
+      def self.valid_string?(value)
+        value.encode(Encoding::UTF_8).valid_encoding?
+      rescue EncodingError
+        false
+      end
+
+      def render(document:, output:, max_bytes:)
+        raise NotImplementedError
+      end
+
+      private
+
+      def each_row(record_set)
+        index = 0
+        record_set.each_row do |row|
+          index += 1
+          self.class.validate_row!(record_set, row)
+
+          yield row
+        end
+      rescue InvalidDocument => e
+        raise e.at(record_set: record_set.name, row: index)
+      rescue JSON::GeneratorError, EncodingError
+        raise InvalidDocument.new(error_details: { record_set: record_set.name, row: index })
+      end
+
+      def manifest_entry(section, counts)
+        {
+          "category" => section.key,
+          "label" => section.label,
+          "description" => section.description,
+          **section.metadata,
+          "record_sets" => counts,
+          "count" => counts.values.sum
+        }
+      end
+
+      def ensure_size!(io, max_bytes)
+        raise TooLarge if io.size > max_bytes
+      end
+    end
+  end
+end

data/lib/export_kit/renderers/csv_archive.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "csv"
+require "tempfile"
+require "zip"
+
+module ExportKit
+  module Renderers
+    # A multi-table document cannot be represented faithfully by one rectangular CSV. This
+    # renderer writes one UTF-8 CSV per non-empty record set plus a deterministic manifest.csv.
+    class CsvArchive < Base
+      MANIFEST_COLUMNS = %w(kind section record_set file count metadata).freeze
+      FORMULA_PREFIX = /\A[=+\-@]/
+
+      def self.csv_value(value)
+        rendered = value.is_a?(Array) ? JSON.generate(value) : value
+        rendered.is_a?(String) && rendered.match?(FORMULA_PREFIX) ? "'#{rendered}" : rendered
+      end
+
+      def render(document:, output:, max_bytes:)
+        manifest = nil
+        Zip::OutputStream.write_buffer(output) do |archive|
+          bounded = Output.new(io: archive, max_bytes:)
+          manifest, files = write_record_sets(document, archive, bounded)
+          write_manifest(document, manifest, files, archive, bounded)
+        end
+        ensure_size!(output, max_bytes)
+        manifest
+      end
+
+      private
+
+      def write_record_sets(document, archive, bounded)
+        state = { files: {} }
+        manifest = document.sections.map { write_section(it, archive, bounded, state) }
+        [manifest, state.fetch(:files)]
+      end
+
+      def write_section(section, archive, bounded, state)
+        counts = section.record_sets.to_h do |record_set|
+          count, filename = write_record_set(section, record_set, archive, bounded)
+
+          state.fetch(:files)[[section.key, record_set.name]] = filename
+          [record_set.name, count]
+        end
+        manifest_entry(section, counts)
+      rescue InvalidDocument => e
+        raise e.at(section: section.key)
+      end
+
+      def write_record_set(section, record_set, archive, bounded)
+        csv = CSV.new(bounded)
+        count = 0
+        each_row(record_set) do |row|
+          start_record_set(archive, csv, section, record_set) if count.zero?
+          csv << record_set.columns.map { self.class.csv_value(row.fetch(it)) }
+          count += 1
+        end
+        [count, record_set_filename(section, record_set, count)]
+      end
+
+      def start_record_set(archive, csv, section, record_set)
+        archive.put_next_entry(record_set_filename(section, record_set, 1))
+        csv << record_set.headers.map { self.class.csv_value(it) }
+      end
+
+      def record_set_filename(section, record_set, count)
+        "data/#{section.key}/#{record_set.name}.csv" if count.positive?
+      end
+
+      def write_manifest(document, manifest, files, archive, bounded)
+        archive.put_next_entry("manifest.csv")
+        csv = CSV.new(bounded)
+        csv << MANIFEST_COLUMNS
+        write_document_manifest(csv, document)
+        document.sections.zip(manifest).each do |section, entry|
+          write_section_manifest(csv, section, entry, files)
+        end
+      end
+
+      def write_document_manifest(csv, document)
+        metadata = {
+          "format" => document.identifier,
+          "schema_version" => document.schema_version,
+          "title" => document.title, **document.metadata
+        }
+        metadata.each { |key, value| csv << ["document", nil, nil, nil, nil, JSON.generate(key => value)] }
+      end
+
+      def write_section_manifest(csv, section, entry, files)
+        csv << ["section", section.key, nil, nil, entry.fetch("count"), JSON.generate(section.metadata)]
+        section.record_sets.each { write_record_set_manifest(csv, section, it, entry, files) }
+      end
+
+      def write_record_set_manifest(csv, section, record_set, entry, files)
+        csv << [
+          "record_set",
+          section.key,
+          record_set.name,
+          files[[section.key, record_set.name]],
+          entry.fetch("record_sets").fetch(record_set.name),
+          JSON.generate("columns" => record_set.columns,
+                        "headers" => record_set.headers.map { self.class.csv_value(it) })
+        ]
+      end
+    end
+  end
+end

data/lib/export_kit/renderers/json.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module ExportKit
+  module Renderers
+    # Canonical, structured representation of an export document.
+    class Json < Base
+      def render(document:, output:, max_bytes:)
+        data_file = Tempfile.new(%w(export-kit-data .json), binmode: true)
+        manifest = write_data(document, Output.new(io: data_file, max_bytes:), max_bytes)
+        assemble(document, manifest, data_file, output, max_bytes)
+        manifest
+      ensure
+        data_file&.close!
+      end
+
+      private
+
+      def write_data(document, data_file, max_bytes)
+        data_file.write("{")
+        manifest = document.sections.each_with_index.map do |section, section_index|
+          data_file.write(",") if section_index.positive?
+          data_file.write("#{JSON.generate(section.key)}:")
+          counts = write_section(section, data_file, max_bytes)
+          manifest_entry(section, counts)
+        end
+        data_file.write("}")
+        manifest
+      end
+
+      def write_section(section, data_file, max_bytes)
+        data_file.write("{")
+        counts = section.record_sets.each_with_index.to_h do |record_set, set_index|
+          data_file.write(",") if set_index.positive?
+          data_file.write("#{JSON.generate(record_set.name)}:")
+          [record_set.name, write_rows(record_set, data_file, max_bytes)]
+        end
+        data_file.write("}")
+        counts
+      rescue InvalidDocument => e
+        raise e.at(section: section.key)
+      end
+
+      def write_rows(record_set, data_file, max_bytes)
+        data_file.write("[")
+        count = 0
+        each_row(record_set) do |row|
+          data_file.write(",") if count.positive?
+          data_file.write(JSON.generate(row))
+          count += 1
+          ensure_size!(data_file, max_bytes)
+        end
+        data_file.write("]")
+        count
+      end
+
+      def assemble(document, manifest, data_file, output, max_bytes)
+        header = JSON.generate(document.envelope(manifest))
+        output.write(header.delete_suffix("}"), ",\"data\":")
+        data_file.rewind
+        output.copy_from(data_file)
+        output.write("}")
+        output.flush
+        ensure_size!(output, max_bytes)
+      end
+    end
+  end
+end

data/lib/export_kit/renderers/pdf.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "prawn"
+
+module ExportKit
+  module Renderers
+    # Human-readable presentation of the same logical document. All source values are plain text;
+    # Prawn never interprets them as HTML or inline markup.
+    class Pdf < Base
+      def initialize(fonts: nil)
+        super()
+        @fonts = fonts
+      end
+
+      def render(document:, output:, max_bytes:)
+        manifest = render_pdf(document, output)
+        ensure_size!(output, max_bytes)
+        manifest
+      end
+
+      private
+
+      attr_reader :fonts
+
+      def render_pdf(document, output)
+        pdf = Prawn::Document.new(page_size: "A4", margin: 42)
+        configure_font(pdf)
+        render_header(pdf, document)
+        manifest = document.sections.map { render_page(pdf, it) }
+        render_manifest(pdf, manifest)
+        render_page_numbers(pdf)
+        pdf.render(output)
+        manifest
+      end
+
+      def render_page(pdf, section)
+        pdf.start_new_page unless pdf.page_number == 1 && pdf.cursor > 300
+        manifest_entry(section, render_section(pdf, section))
+      end
+
+      def configure_font(pdf)
+        normal = fonts && fonts[:normal]
+        bold = fonts && fonts[:bold]
+        raise InvalidDocument, "Unicode PDF font is unavailable" unless normal && File.file?(normal)
+
+        pdf.font_families.update("ExportSans" => { normal:, bold: bold || normal })
+        pdf.font("ExportSans")
+      end
+
+      def render_header(pdf, document)
+        pdf.text printable(document.title), size: 20, style: :bold
+        pdf.move_down 12
+        pdf.text "Format: #{printable(document.identifier)} · schema: #{document.schema_version}", size: 9
+        document.metadata.each { |key, value| render_field(pdf, key, value, size: 8) }
+      end
+
+      def render_section(pdf, section)
+        render_section_header(pdf, section)
+        section.record_sets.to_h do |record_set|
+          [record_set.name, render_record_set(pdf, record_set)]
+        end
+      rescue InvalidDocument => e
+        raise e.at(section: section.key)
+      end
+
+      def render_section_header(pdf, section)
+        pdf.text printable(section.label), size: 16, style: :bold
+        pdf.text printable(section.description), size: 9 unless section.description.empty?
+        pdf.move_down 10
+      end
+
+      def render_record_set(pdf, record_set)
+        pdf.text printable(record_set.name), size: 12, style: :bold
+        count = 0
+        each_row(record_set) do |row|
+          count += 1
+          render_record(pdf, record_set, row, count)
+        end
+        pdf.text "—", size: 9 if count.zero?
+        pdf.move_down 12
+        count
+      end
+
+      def render_record(pdf, record_set, row, count)
+        pdf.start_new_page if pdf.cursor < record_height(pdf, record_set, row, count)
+        pdf.move_down 6
+        pdf.text "##{count}", size: 9, style: :bold
+        row.each { |key, value| render_field(pdf, record_set.column_labels.fetch(key), value) }
+      end
+
+      def record_height(pdf, record_set, row, count)
+        heading_height = pdf.height_of("##{count}", size: 9, style: :bold)
+        fields_height = row.sum do |key, value|
+          pdf.height_of(field_text(record_set.column_labels.fetch(key), value), size: 8, leading: 1)
+        end
+        6 + heading_height + fields_height
+      end
+
+      def render_field(pdf, key, value, size: 8)
+        pdf.text field_text(key, value), size:, leading: 1
+      end
+
+      def field_text(key, value)
+        rendered = value.is_a?(Array) ? JSON.generate(value) : value.to_s
+        "#{printable(key)}: #{printable(rendered)}"
+      end
+
+      def render_manifest(pdf, manifest)
+        pdf.start_new_page
+        pdf.text "Manifest", size: 16, style: :bold
+        pdf.move_down 8
+        manifest.each do |entry|
+          pdf.text "#{printable(entry.fetch('label'))}: #{entry.fetch('count')}", size: 9
+        end
+      end
+
+      def render_page_numbers(pdf)
+        pdf.number_pages("<page> / <total>", at: [pdf.bounds.right - 70, -18], width: 70, align: :right, size: 8)
+      end
+
+      def printable(value)
+        value.to_s.encode("UTF-8", invalid: :replace, undef: :replace, replace: "�")
+             .gsub(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/, " ")
+      end
+    end
+  end
+end

data/lib/export_kit/result.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ExportKit
+  class Result
+    class ValueError < StandardError; end
+
+    attr_reader :value, :error, :error_details
+
+    def self.success(value) = new(value:, error: nil)
+
+    def self.failure(error, error_details: {})
+      raise ArgumentError, "error must be a symbol" unless error.is_a?(Symbol)
+
+      new(value: nil, error:, error_details:)
+    end
+
+    def initialize(value:, error:, error_details: {})
+      raise ArgumentError, "error must be a symbol" unless error.nil? || error.is_a?(Symbol)
+
+      @value = value
+      @error = error
+      @error_details = safe_details(error_details)
+      freeze
+    end
+
+    def success? = error.nil?
+    def failure? = !success?
+
+    def value!
+      raise ValueError, error.to_s if failure?
+
+      value
+    end
+
+    def map
+      success? ? self.class.success(yield(value)) : self
+    end
+
+    def map_error
+      failure? ? self.class.failure(yield(error), error_details:) : self
+    end
+
+    def and_then
+      success? ? yield(value) : self
+    end
+
+    private
+
+    def safe_details(details)
+      details.each_with_object({}) do |(key, detail), safe|
+        value = safe_detail(key, detail)
+        safe[key] = value unless value.nil?
+      end.freeze
+    end
+
+    def safe_detail(key, detail)
+      return safe_row(detail) if key == :row
+      return unless %i(section record_set column).include?(key)
+      return unless detail.is_a?(String) || detail.is_a?(Symbol)
+
+      detail.to_s.dup.freeze if detail.to_s.match?(Document::KEY_FORMAT)
+    end
+
+    def safe_row(detail)
+      detail if detail.is_a?(Integer) && detail.positive?
+    end
+  end
+end

data/lib/export_kit/table.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ExportKit
+  class Table < Document::RecordSet
+    def initialize(columns:, rows:, labels: {})
+      source = rows.respond_to?(:call) ? rows : ->(&emit) { rows.each(&emit) }
+      super(name: "rows", columns:, column_labels: labels, row_source: source)
+    end
+
+    def each_row
+      index = 0
+      super do |row|
+        index += 1
+        yield normalize(row)
+      end
+    rescue Renderers::InvalidDocument => e
+      raise e.at(record_set: name, row: index)
+    end
+
+    private
+
+    def normalize(row)
+      validate_keys!(row)
+      validate_row_columns!(row.keys.map(&:to_s))
+      normalized = row.transform_keys(&:to_s)
+      columns.to_h { [it, normalized.fetch(it)] }
+    end
+
+    def validate_row_columns!(keys)
+      return if keys.uniq == keys && keys.sort == columns.sort
+
+      raise Renderers::InvalidDocument.new(error_details: { column: (columns - keys).first })
+    end
+
+    def validate_keys!(row)
+      return if row.is_a?(Hash) && row.keys.all? { it.is_a?(String) || it.is_a?(Symbol) }
+
+      raise Renderers::InvalidDocument
+    end
+  end
+end