export_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 401631ec4132efca4eb76e051db2e90bef4e3371610198ae45e311a4d11f446b
+  data.tar.gz: 9e1b1d4c5bf0fe15c7d0848c00903453548f52c58362eed1749235416ce852f7
+SHA512:
+  metadata.gz: 69afffa72dec01eea9973e2f2aefff6c7956562bcf4ce56f7b442717f79d02e624b593d74cee98cf825fded7060f7ff90c61fc5d762b5b3e3f97a17e667d3c26
+  data.tar.gz: 8e626eaecd333db03433bd5ec756922f2beed0796711fd6015bcdaadf233ab328f8f67a9dc58ab95871104ae4b3f0ccb0ba370ac1caf33581c0f37e71d2bf3e7

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2026-10-26
+
+First public release.
+
+- Renders hashes and explicit tables as JSON or CSV.
+- Renders multi-section documents as JSON, ZIP archives of CSV tables, or PDF.
+- Enforces a caller-provided output-size limit while data is written.
+- Neutralizes spreadsheet formulas in CSV cells.
+- Returns typed results for expected failures and removes partial temporary files.
+- Verifies artifact digests and validates the structure of supported formats.
+- Provides an optional Active Record adapter with explicit allow/deny schemas and keyset batching.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Łukasz Kerl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,242 @@
+# ExportKit
+
+Portable, size-bounded exports for Ruby applications.
+
+ExportKit turns plain Ruby data, explicit tables or multi-section documents into JSON, CSV,
+ZIP archives of CSV tables, and PDF. It streams rows, stops writing at a caller-provided byte
+limit, neutralizes spreadsheet formulas, removes partial temporary files and can validate the
+artifact it produced.
+
+*(Dokumentacja po polsku: [README.pl.md](README.pl.md))*
+
+## Why this exists
+
+An export is more than `CSV.generate`: the caller must decide what may leave the application,
+preserve a stable schema, avoid loading an unbounded dataset, prevent formula injection, clean up
+temporary files and distinguish an expected refusal from a programming error. ExportKit owns those
+format-neutral mechanics. The application still owns authorization and the business meaning of the
+data.
+
+The core does not load Rails or Active Record. The optional adapter is enabled explicitly.
+
+## Installation
+
+```ruby
+gem "export_kit", "~> 0.1.0"
+```
+
+ExportKit requires Ruby 3.4 or newer.
+
+## A single table
+
+```ruby
+require "export_kit"
+require "fileutils"
+
+table = ExportKit::Table.new(
+  columns: %i[sku name price],
+  labels: { sku: "SKU", name: "Name", price: "Price" },
+  rows: [
+    { sku: "LAMP-01", name: "Ceramic lamp", price: "149.00" },
+    { sku: "CHAIR-02", name: "=HYPERLINK(...)", price: "320.00" }
+  ]
+)
+
+result = ExportKit.render(table, format: :csv, max_bytes: 5 * 1024**2)
+
+if result.success?
+  artifact = result.value!
+  begin
+    FileUtils.copy_file(artifact.file.path, "products.csv")
+  ensure
+    artifact.close!
+  end
+else
+  warn result.error
+end
+```
+
+Column order is explicit. Every row must contain exactly the declared keys. CSV headers use the
+labels, while JSON keeps the stable column keys. Strings beginning with `=`, `+`, `-` or `@` are
+prefixed with an apostrophe in CSV output to prevent spreadsheet formula execution.
+
+`rows` may also be a callback, which avoids materializing the whole dataset:
+
+```ruby
+rows = lambda do |&emit|
+  source.each_batch { |batch| batch.each { |record| emit.call(record) } }
+end
+
+table = ExportKit::Table.new(columns: %i[id name], rows: rows)
+```
+
+The source is consumed synchronously and once per render.
+
+## Plain JSON
+
+Plain hashes and arrays can be rendered directly as JSON:
+
+```ruby
+result = ExportKit.render(
+  { product: { sku: "LAMP-01", tags: ["vintage"] } },
+  format: :json,
+  max_bytes: 1_000_000
+)
+```
+
+Supported values are hashes with string or symbol keys, arrays, strings, finite numbers, booleans
+and `nil`. Nesting deeper than 100 levels is rejected.
+
+## Multi-section documents
+
+`ExportKit::Document` describes a versioned export independently of its output format. Each record
+set is an explicit table backed by a row callback.
+
+```ruby
+users = ExportKit::Document::RecordSet.new(
+  name: "users",
+  columns: %i[id email],
+  column_labels: { id: "ID", email: "Email" },
+  row_source: ->(&emit) { authorized_users.find_each { |user| emit.call(id: user.id, email: user.email) } }
+)
+
+people = ExportKit::Document::Section.new(
+  key: "people",
+  label: "People",
+  description: "Authorized user records",
+  metadata: {},
+  record_sets: [users]
+)
+
+document = ExportKit::Document.new(
+  identifier: "account_export",
+  schema_version: 1,
+  title: "Account export",
+  metadata: { requested_by: { user_id: 42 } },
+  sections: [people]
+)
+
+result = ExportKit.render(document, format: :csv_zip, max_bytes: 20 * 1024**2)
+```
+
+Supported document formats:
+
+| format | artifact | notes |
+|---|---|---|
+| `json` | `.json` | versioned envelope, manifest and section data |
+| `csv_zip` | `.zip` | one UTF-8 CSV per non-empty record set plus `manifest.csv` |
+| `pdf` | `.pdf` | human-readable A4 report; requires an explicit Unicode font |
+
+For PDF, provide a font file owned by the consuming application:
+
+```ruby
+ExportKit.render(
+  document,
+  format: :pdf,
+  max_bytes: 20 * 1024**2,
+  font: Rails.root.join("app/assets/fonts/Inter-Regular.ttf").to_s,
+  bold_font: Rails.root.join("app/assets/fonts/Inter-Bold.ttf").to_s
+)
+```
+
+## Active Record adapter
+
+Load the adapter explicitly:
+
+```ruby
+require "export_kit/active_record"
+```
+
+For a direct table, pass an authorized relation and a field allowlist:
+
+```ruby
+table = ExportKit.records(
+  policy_scope(Order).reorder(nil),
+  fields: %i[id number total_minor],
+  labels: { number: "Order", total_minor: "Total (minor units)" },
+  batch_size: 500
+)
+```
+
+Models may define a complete export policy and use `fields: :all` in serializer definitions:
+
+```ruby
+class User < ApplicationRecord
+  include ExportKit::ModelSchema
+
+  export_schema do
+    allow :id, :email
+    timestamps
+    omit :password_digest, :reset_token, reason: "authentication secrets"
+  end
+end
+
+User.validate_export_schema!
+```
+
+The validation requires every database column to be either allowed or denied with a reason. This
+is a schema ratchet, not authorization. The application must still provide the correct scoped
+relation.
+
+The batching adapter accepts an unordered, ungrouped relation without `offset` or `distinct`, and
+requires a single primary key. It paginates by that primary key and respects an existing `limit`.
+
+## Results and cleanup
+
+Expected render failures are returned as `ExportKit::Result`:
+
+| error | meaning |
+|---|---|
+| `export_format_unsupported` | no renderer exists for the requested format |
+| `export_too_large` | the byte limit was exceeded |
+| `export_render_failed` | input or renderer output was invalid |
+
+`Result` provides `success?`, `failure?`, `value`, `value!`, `error`, `error_details`, `map`,
+`map_error` and `and_then`. Safe error details may identify a section, record set, row and column;
+they never contain the rejected value.
+
+Programming errors from a custom renderer or row source propagate after temporary output is
+removed. The caller owns a successful artifact and must call `close!` (or its alias `cleanup`) in
+an `ensure` block.
+
+## Validation
+
+```ruby
+artifact.verify                 # digest and byte count
+ExportKit.validate(artifact)    # digest plus supported-format structure
+```
+
+Validation detects accidental corruption and malformed manifests. It does not prove that the
+application selected every required record or excluded every private field.
+
+## Security boundaries
+
+ExportKit provides bounded writes, CSV formula neutralization, explicit schemas, safe error
+locations, temporary-file cleanup and structural validation. It deliberately does not provide:
+
+- authentication or authorization;
+- tenant or policy scoping;
+- transactional snapshots across several queries;
+- encryption, object storage, downloads or retention;
+- privacy-law completeness checks;
+- a safe sandbox for custom renderers.
+
+Treat custom renderers as trusted application code. Do not expose artifact paths in logs or error
+responses. Set `max_bytes` from an application-level policy and deliver artifacts through an
+authorized channel.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake test
+bundle exec rubocop
+gem build export_kit.gemspec
+```
+
+The test suite does not use the network. See [CONTRIBUTING.md](CONTRIBUTING.md),
+[SECURITY.md](SECURITY.md) and [docs/releasing.md](docs/releasing.md).
+
+## License
+
+The gem is available under the [MIT License](LICENSE.txt).

data/README.pl.md

@@ -0,0 +1,113 @@
+# ExportKit
+
+Przenośne eksporty Ruby z jawnym limitem rozmiaru.
+
+ExportKit zamienia zwykłe dane Ruby, jawne tabele albo dokumenty z wieloma sekcjami na JSON, CSV,
+archiwa ZIP z tabelami CSV oraz PDF. Strumieniuje wiersze, zatrzymuje zapis po przekroczeniu limitu,
+neutralizuje formuły arkusza, sprząta częściowe pliki tymczasowe i potrafi sprawdzić wynikowy artefakt.
+
+Pełna dokumentacja API i przykłady znajdują się w angielskim [README.md](README.md). Ten plik
+podsumowuje kontrakt integracyjny po polsku.
+
+## Instalacja
+
+```ruby
+gem "export_kit", "~> 0.1.0"
+```
+
+Wymagany jest Ruby 3.4 lub nowszy. Rdzeń nie uruchamia Rails ani Active Record. Adapter modeli
+włącza się jawnie przez `require "export_kit/active_record"`.
+
+## Pojedyncza tabela
+
+```ruby
+require "export_kit"
+
+table = ExportKit::Table.new(
+  columns: %i[number total],
+  labels: { number: "Numer", total: "Kwota" },
+  rows: [{ number: "GV-001", total: "149.00" }]
+)
+
+result = ExportKit.render(table, format: :csv, max_bytes: 5 * 1024**2)
+
+if result.success?
+  artifact = result.value!
+  begin
+    send_data artifact.file.read, type: artifact.content_type
+  ensure
+    artifact.close!
+  end
+end
+```
+
+Każdy wiersz musi mieć dokładnie zadeklarowane kolumny. Kolejność kolumn jest stabilna. Wartości
+CSV zaczynające się od `=`, `+`, `-` albo `@` dostają apostrof, aby arkusz nie wykonał ich jako
+formuły. `rows` może być callbackiem przyjmującym blok `emit`, dzięki czemu nie trzeba budować całej
+tablicy w pamięci.
+
+## Formaty
+
+- zwykły Hash lub Array: `json`;
+- `ExportKit::Table`: `json` albo `csv`;
+- `ExportKit::Document`: `json`, `csv_zip` albo `pdf`.
+
+Dokument składa się z wersjonowanego identyfikatora, metadanych, sekcji i nazwanych zestawów
+rekordów. ZIP zawiera osobny CSV dla każdego niepustego zestawu oraz `manifest.csv`. PDF wymaga
+jawnej ścieżki do fontu Unicode dostarczonego przez aplikację.
+
+## Wynik i sprzątanie
+
+Oczekiwane odmowy nie rzucają wyjątku:
+
+- `export_format_unsupported` — nieobsługiwany format;
+- `export_too_large` — przekroczony limit bajtów;
+- `export_render_failed` — niepoprawne dane albo wynik renderera.
+
+Szczegóły błędu mogą wskazać sekcję, zestaw, wiersz i kolumnę, ale nie zawierają wartości danych.
+Błędy programistyczne propagują wyjątek po usunięciu pliku częściowego. Udany artefakt należy
+zawsze zamknąć przez `close!`/`cleanup` w `ensure`.
+
+## Active Record
+
+```ruby
+require "export_kit/active_record"
+
+table = ExportKit.records(
+  policy_scope(Order).reorder(nil),
+  fields: %i[id number total_minor],
+  batch_size: 500
+)
+```
+
+Adapter wymaga relacji już ograniczonej przez aplikację. Może także pilnować kompletnej klasyfikacji
+kolumn modelu: każda kolumna trafia wtedy na jawną allowlistę albo denylistę z powodem. To bezpiecznik
+schematu, nie zamiennik Pundita ani innej autoryzacji.
+
+Relacja do stronicowania musi być bez `order`, `offset`, `group` i `distinct` oraz mieć pojedynczy
+klucz główny. Adapter stronicuje po kluczu i respektuje istniejący `limit`.
+
+## Granica odpowiedzialności
+
+Biblioteka odpowiada za mechanikę formatów, limity zapisu, neutralizację formuł, sprzątanie i
+walidację struktury. Aplikacja odpowiada za:
+
+- uwierzytelnienie, autoryzację i zakres danych;
+- spójność odczytu;
+- minimalizację danych i zgodność z wymaganiami prywatności;
+- szyfrowanie, storage, pobieranie i retencję;
+- zaufanie do własnych rendererów.
+
+## Rozwój i wydania
+
+```bash
+bin/setup
+bundle exec rake test
+bundle exec rubocop
+gem build export_kit.gemspec
+```
+
+Wydania idą z GitHub Actions do RubyGems.org przez OIDC Trusted Publishing, bez długowiecznego
+tokena w sekretach repo. Szczegóły: [docs/releasing.md](docs/releasing.md).
+
+Kod jest dostępny na licencji [MIT](LICENSE.txt).

data/lib/export_kit/active_record.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "export_kit"
+require "active_record"
+require "export_kit/model_schema"
+require "export_kit/model_serializer"
+require "export_kit/model_rows"
+
+module ExportKit
+  def self.records(scope, fields:, labels: {}, batch_size: 500)
+    set = ModelSerializer::RecordSetBuilder.new(
+      "rows", model: scope.klass, scope: ->(_) { scope }, fields:, schema: nil
+    ).build
+    Table.new(columns: set.output_keys, labels:, rows: ->(&emit) { set.each_row(batch_size:, &emit) })
+  end
+end

data/lib/export_kit/artifact.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ExportKit
+  Artifact = Data.define(:file, :byte_size, :sha256, :manifest, :format, :content_type, :extension,
+                         :identifier, :schema_version, :metadata, :document) do
+    def close!
+      file.close!
+      nil
+    end
+    alias_method :cleanup, :close!
+
+    def verify
+      valid ? Result.success(self) : Result.failure(ValidateArtifact::INVALID)
+    rescue Errno::ENOENT, IOError
+      Result.failure(ValidateArtifact::INVALID)
+    end
+
+    private
+
+    def valid = file.path && File.size(file.path) == byte_size && Digest::SHA256.file(file.path).hexdigest == sha256
+  end
+end

data/lib/export_kit/document.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module ExportKit
+  # Format-neutral input for export renderers. A source adapter describes the document and
+  # streams rows; renderers know nothing about Active Record or the domain that produced them.
+  class Document
+    KEY_FORMAT = /\A[a-z][a-z0-9_]{0,63}\z/
+    IDENTIFIER_FORMAT = /\A[a-z][a-z0-9_]{2,63}\z/
+
+    attr_reader :identifier, :metadata, :schema_version, :sections, :title
+
+    def self.string(value) = value.to_s.dup.freeze
+
+    def self.normalize_metadata(value, depth = 0)
+      raise ArgumentError, "metadata nesting exceeds limit" if depth > 100
+
+      case value
+      when Hash then normalize_hash(value, depth)
+      when Array then value.map { normalize_metadata(it, depth + 1) }.freeze
+      when String then value.dup.freeze
+      when Integer, Float, TrueClass, FalseClass, NilClass then value
+      else raise ArgumentError, "unsupported metadata value"
+      end
+    end
+
+    def self.normalize_hash(value, depth)
+      keys = value.keys.map(&:to_s)
+      raise ArgumentError, "duplicate metadata keys" unless keys.uniq == keys
+
+      value.to_h { |key, item| [string(key), normalize_metadata(item, depth + 1)] }.freeze
+    end
+
+    def self.validate_metadata!(metadata, reserved)
+      raise ArgumentError, "metadata must be a hash" unless metadata.is_a?(Hash)
+      raise ArgumentError, "reserved metadata key" if metadata.keys.intersect?(reserved)
+    end
+
+    # One logical group in a document. Metadata is copied into every format manifest.
+    class Section
+      attr_reader :description, :key, :label, :metadata, :record_sets
+
+      def initialize(key:, label:, description:, metadata:, record_sets:)
+        @key = Document.string(key)
+        @label = Document.string(label)
+        @description = Document.string(description)
+        @metadata = Document.normalize_metadata(metadata)
+        @record_sets = Array(record_sets).dup.freeze
+        validate!
+      end
+
+      private
+
+      def validate!
+        Document.validate_metadata!(metadata, %w(category label description record_sets count))
+        raise ArgumentError, "invalid export section key" unless key.match?(KEY_FORMAT)
+        raise ArgumentError, "export section label is required" if label.strip.empty?
+
+        validate_record_sets!
+      end
+
+      def validate_record_sets!
+        raise ArgumentError, "invalid record sets" unless record_sets.all?(RecordSet)
+        return if record_sets.map(&:name).uniq.size == record_sets.size
+
+        raise ArgumentError, "export record-set names must be unique"
+      end
+    end
+
+    # A named table with an explicit column order and a callback that yields one Hash per row.
+    class RecordSet
+      attr_reader :column_labels, :columns, :name
+
+      def initialize(name:, columns:, row_source:, column_labels: {})
+        @name = Document.string(name)
+        @columns = Array(columns).map { Document.string(it) }.freeze
+        @column_labels = @columns.to_h { [it, it] }.merge(
+          column_labels.to_h { |key, value| [Document.string(key), Document.string(value)] }
+        ).freeze
+        @row_source = row_source
+        validate!
+      end
+
+      def headers
+        columns.map { column_labels.fetch(it) }
+      end
+
+      def each_row(&)
+        row_source.call(&)
+      end
+
+      private
+
+      attr_reader :row_source
+
+      def validate!
+        validate_name!
+        validate_columns!
+        validate_labels!
+        validate_row_source!
+      end
+
+      def validate_name!
+        raise ArgumentError, "invalid export record-set name" unless name.match?(KEY_FORMAT)
+      end
+
+      def validate_columns!
+        raise ArgumentError, "export columns must be unique" unless columns.uniq.size == columns.size
+      end
+
+      def validate_labels!
+        raise ArgumentError, "export column labels must match columns" unless column_labels.keys == columns
+        raise ArgumentError, "export column labels must be unique" unless headers.uniq.size == headers.size
+        raise ArgumentError, "export column labels must be present" if headers.any? { it.to_s.strip.empty? }
+      end
+
+      def validate_row_source!
+        raise ArgumentError, "export row source must be callable" unless row_source.respond_to?(:call)
+      end
+    end
+
+    def initialize(identifier:, schema_version:, title:, metadata:, sections:)
+      @identifier = Document.string(identifier)
+      @schema_version = Integer(schema_version)
+      @title = Document.string(title)
+      @metadata = Document.normalize_metadata(metadata)
+      @sections = Array(sections).dup.freeze
+      validate!
+    end
+
+    def envelope(manifest)
+      { "format" => identifier, "schema_version" => schema_version, **metadata, "manifest" => manifest }
+    end
+
+    private
+
+    def validate!
+      Document.validate_metadata!(metadata, %w(format schema_version manifest data))
+      validate_identifier!
+      validate_schema_version!
+      validate_title!
+      validate_sections!
+    end
+
+    def validate_identifier!
+      raise ArgumentError, "invalid export document identifier" unless identifier.match?(IDENTIFIER_FORMAT)
+    end
+
+    def validate_schema_version!
+      raise ArgumentError, "invalid export schema version" unless schema_version.positive?
+    end
+
+    def validate_title!
+      raise ArgumentError, "export document title is required" if title.strip.empty?
+    end
+
+    def validate_sections!
+      unless sections.all?(Section)
+        raise ArgumentError, "export document sections must be ExportKit::Document::Section instances"
+      end
+      return if sections.map(&:key).uniq.size == sections.size
+
+      raise ArgumentError, "export document needs unique sections"
+    end
+  end
+end

data/lib/export_kit/format_registry.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ExportKit
+  module FormatRegistry
+    Definition = Data.define(:key, :extension, :content_type)
+    DEFINITIONS = [
+      Definition.new(key: "json", extension: "json", content_type: "application/json"),
+      Definition.new(key: "csv", extension: "csv", content_type: "text/csv"),
+      Definition.new(key: "csv_zip", extension: "zip", content_type: "application/zip"),
+      Definition.new(key: "pdf", extension: "pdf", content_type: "application/pdf")
+    ].to_h { [it.key, it] }.freeze
+
+    def self.find(key) = DEFINITIONS[key.to_s]
+  end
+end