typstify 0.1.0

data/lib/typstify/adapter.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "typst"
+
+module Typstify
+  # The only file in this gem that knows the `typst` binding exists.
+  #
+  # Everything upstream might rename — the constructor shape, the option names,
+  # how compiled bytes come back — is contained here, so a binding release
+  # breaks one file instead of five. Verified against typst 0.15.1.5.
+  module Adapter
+    # The binding surfaces compile failures as ArgumentError, carrying the same
+    # codespan-formatted diagnostic the CLI prints.
+    BINDING_ERROR = ArgumentError
+
+    module_function
+
+    # @param main_path [Pathname] the workspace's main.typ
+    # @param root [Pathname] the workspace; Typst's sandbox boundary
+    # @param template [String] the name to show in errors
+    # @param config [Typstify::Config] supplies the fonts and the PDF standard
+    # @return [String] PDF bytes, ASCII-8BIT
+    def compile_pdf(main_path:, root:, template:, config: Typstify.config)
+      document = Typst(
+        main_path.to_s,
+        root: root.to_s,
+        font_paths: config.font_paths.map(&:to_s),
+        ignore_system_fonts: config.ignore_system_fonts,
+        pdf_standards: config.pdf_standards
+      ).compile(:pdf)
+
+      # PdfDocument#bytes is a per-page array of integer arrays; #pages packs
+      # each one. A PDF is always a single "page" here — the whole document.
+      document.pages.first.to_s.b
+    rescue BINDING_ERROR => e
+      raise translate(e, root: root, template: template, config: config)
+    end
+
+    # Turn the binding's flat diagnostic blob into a CompileError that names the
+    # developer's template rather than a tmpdir, and surface any warnings that
+    # came along with it through the on_warning hook.
+    def translate(error, root:, template:, config:)
+      readable = Warnings.rewrite_paths(error.message, root, template)
+      diagnostics = Warnings.parse(readable)
+      Warnings.dispatch(diagnostics, template, config)
+
+      first = diagnostics.find { |d| d.severity == :error }
+      CompileError.new(
+        template: template,
+        typst_message: readable.strip,
+        line: first&.line,
+        column: first&.column
+      )
+    end
+  end
+end

data/lib/typstify/config.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Typstify
+  # Everything tunable, set once in `config/initializers/typstify.rb`.
+  #
+  #   Typstify.configure do |c|
+  #     c.font_paths   = [Rails.root.join("app/assets/fonts")]
+  #     c.pdf_standard = :ua_1
+  #   end
+  class Config
+    # Symbol names for the PDF standards Typst can emit, mapped to the strings
+    # the compiler wants. Verified against typst_pdf::PdfStandard.
+    PDF_STANDARDS = {
+      pdf_1_7: "1.7",
+      pdf_2_0: "2.0",
+      a_1b: "a-1b",
+      a_2b: "a-2b",
+      a_3b: "a-3b",
+      a_4: "a-4",
+      ua_1: "ua-1"
+    }.freeze
+
+    attr_writer :template_root, :shared_dir, :font_paths, :package_cache, :on_warning,
+                :strict_fonts, :ignore_system_fonts
+
+    # Where `.typ` templates live. Also the boundary a template path may not
+    # escape (see Resolver).
+    def template_root
+      @template_root ||= defined?(::Rails) && ::Rails.root ? ::Rails.root.join("app/views") : Pathname.pwd
+      Pathname.new(@template_root)
+    end
+
+    # Subdirectory of `template_root` copied into every workspace, so
+    # `#import "shared/branding.typ"` resolves from any template.
+    def shared_dir
+      @shared_dir ||= "shared"
+    end
+
+    # Directories searched for fonts, in addition to system fonts. The gem's
+    # own bundled faces are always appended, so starter templates work with no
+    # configuration at all.
+    def font_paths
+      Array(@font_paths).map { |p| Pathname.new(p) } + [Typstify.bundled_font_path]
+    end
+
+    # Directory holding vendored Typst Universe packages, for network-free
+    # builds. See docs/fonts-and-docker.md for the platform caveat.
+    def package_cache
+      @package_cache && Pathname.new(@package_cache)
+    end
+
+    # Skip the operating system's font directories entirely and use only
+    # `font_paths` plus Typst's embedded faces.
+    #
+    # Worth knowing: scanning system fonts costs roughly 50 ms *per render*. On
+    # a styled A4 invoice on an M-series Mac, 58 ms becomes 4 ms with this on.
+    # Once you have vendored the fonts your templates name — which you should;
+    # see docs/fonts-and-docker.md — nothing on the system is being used
+    # anyway, and a slim container has no system fonts to find at all.
+    #
+    # Off by default, because turning it on changes which face a template that
+    # names "Helvetica" ends up with.
+    def ignore_system_fonts
+      @ignore_system_fonts.nil? ? false : @ignore_system_fonts
+    end
+
+    # nil (plain PDF), or one of PDF_STANDARDS' keys.
+    attr_accessor :pdf_standard
+
+    # The compiler flag string, or nil.
+    def pdf_standards
+      return [] if pdf_standard.nil?
+
+      key = pdf_standard.to_sym
+      value = PDF_STANDARDS[key]
+      unless value
+        raise ArgumentError,
+              "Unknown pdf_standard #{pdf_standard.inspect}. " \
+              "Expected one of: #{PDF_STANDARDS.keys.map(&:inspect).join(", ")}"
+      end
+      [value]
+    end
+
+    # Raise FontMissingError instead of warning when a template asks for a font
+    # nothing can supply. On in development and test, off in production, where
+    # a substituted glyph beats a 500.
+    def strict_fonts
+      return @strict_fonts unless @strict_fonts.nil?
+
+      @strict_fonts = !defined?(::Rails) || ::Rails.env.nil? || ::Rails.env.development? || ::Rails.env.test?
+    end
+
+    # Called as `on_warning.call(warnings, template)` — warnings is an Array of
+    # strings. Defaults to Rails.logger.warn.
+    def on_warning
+      @on_warning ||= lambda do |warnings, template|
+        message = "[typstify] #{template}: #{warnings.join("; ")}"
+        if defined?(::Rails) && ::Rails.logger
+          ::Rails.logger.warn(message)
+        else
+          warn(message)
+        end
+      end
+    end
+  end
+end

data/lib/typstify/data.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+require "date"
+
+module Typstify
+  # Turns the `data:` you pass into the `data.json` a template reads.
+  #
+  # The validation pass exists so that a bad value fails immediately, naming the
+  # exact key path, instead of surfacing later as a template that silently
+  # renders "#<Invoice:0x00007f…>" — or, under Rails, as an empty object.
+  #
+  # That last case is the subtle one. ActiveSupport defines `as_json` on
+  # `Object` itself, returning the instance variables of anything at all, so a
+  # naive `respond_to?(:as_json)` check would happily serialise a Proc, an IO or
+  # a half-built value object into `{}` and render a blank invoice. We therefore
+  # accept `as_json` only from classes that actually define it — models,
+  # serializers, Hash, Array, Time — and reject the generic fallback.
+  module Data
+    PRIMITIVES = [String, Integer, TrueClass, FalseClass, NilClass].freeze
+
+    # `as_json` inherited from one of these is ActiveSupport's catch-all, not a
+    # deliberate serialization.
+    GENERIC_AS_JSON_OWNERS = [Object, Kernel, BasicObject].freeze
+
+    module_function
+
+    # @param data [Object] any JSON-serializable structure
+    # @return [String] pretty JSON, ready to write as data.json
+    # @raise [ArgumentError] naming the key path of the first bad value
+    def dump(data)
+      JSON.pretty_generate(normalize(data, ["data"]))
+    end
+
+    def normalize(value, path)
+      case value
+      when *PRIMITIVES        then value
+      when Symbol             then value.to_s
+      when Float              then normalize_float(value, path)
+      when Hash               then normalize_hash(value, path)
+      when Array              then value.each_with_index.map { |v, i| normalize(v, path + ["[#{i}]"]) }
+      when Time, Date         then value.iso8601
+      else                         normalize_object(value, path)
+      end
+    end
+
+    def normalize_hash(hash, path)
+      hash.each_with_object({}) do |(key, value), out|
+        unless key.is_a?(String) || key.is_a?(Symbol) || key.is_a?(Numeric)
+          raise ArgumentError, "#{join(path)} has a #{key.class} key (#{key.inspect}); " \
+                               "JSON object keys must be strings, symbols or numbers."
+        end
+
+        out[key.to_s] = normalize(value, path + [".#{key}"])
+      end
+    end
+
+    def normalize_float(float, path)
+      return float if float.finite?
+
+      raise ArgumentError, "#{join(path)} is #{float}, which JSON cannot represent."
+    end
+
+    def normalize_object(value, path)
+      if deliberate_as_json?(value)
+        normalize(value.as_json, path)
+      elsif deliberate_to_h?(value)
+        normalize(value.to_h, path)
+      else
+        raise ArgumentError, <<~MSG.strip
+          #{join(path)} is a #{value.class}, which is not JSON-serializable.
+
+          Convert it first — a serializer, a class that defines #as_json, or a plain
+          Hash of strings and numbers. Passing it through would put an empty object
+          or an inspect string into your document.
+        MSG
+      end
+    end
+
+    # True when the object's class defines as_json itself, rather than picking
+    # up ActiveSupport's Object-level fallback.
+    def deliberate_as_json?(value)
+      return false unless value.respond_to?(:as_json)
+
+      !GENERIC_AS_JSON_OWNERS.include?(value.method(:as_json).owner)
+    rescue NameError
+      false
+    end
+
+    def deliberate_to_h?(value)
+      return false unless value.respond_to?(:to_h)
+
+      !GENERIC_AS_JSON_OWNERS.include?(value.method(:to_h).owner)
+    rescue NameError
+      false
+    end
+
+    # ["data", ".line_items", "[0]", ".amount"] => data.line_items[0].amount
+    def join(path)
+      path.join
+    end
+  end
+end

data/lib/typstify/document.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Typstify
+  # The pipeline: resolve a template, build an isolated workspace, check fonts,
+  # compile, hand back bytes. Everything public in this gem funnels through here.
+  class Document
+    def initialize(template:, data: nil, assigns: {}, config: Typstify.config)
+      @template = template
+      @data = data
+      @assigns = assigns
+      @config = config
+    end
+
+    # @return [String] PDF bytes, ASCII-8BIT
+    def to_pdf
+      # Validate first: a bad value should fail before we create a workspace,
+      # let alone start the compiler.
+      payload = @data.nil? ? nil : Data.dump(@data)
+      resolution = Resolver.new(@config).call(@template)
+      source = read_source(resolution)
+
+      Workspace.build(source: source, data: payload, config: @config) do |workspace|
+        check_fonts(workspace)
+        Adapter.compile_pdf(
+          main_path: workspace.main_path,
+          root: workspace.dir,
+          template: resolution.name,
+          config: @config
+        )
+      end
+    end
+
+    private
+
+    def read_source(resolution)
+      # Explicit UTF-8: templates contain typographic characters, and a
+      # container with no LANG set defaults to US-ASCII, which would turn an
+      # em dash into an encoding error at render time.
+      raw = File.read(resolution.path, encoding: Encoding::UTF_8)
+      return raw unless resolution.erb?
+
+      ErbPipeline.render(raw, data: @data, assigns: @assigns)
+    end
+
+    # Stands in for the compiler warning we cannot see yet. Checks the main
+    # template and everything copied alongside it, because a missing family is
+    # just as likely to be declared in shared/branding.typ.
+    def check_fonts(workspace)
+      sources = [workspace.main_path, *Dir.glob(workspace.dir.join("**", "*.typ"))]
+      combined = sources.uniq.map { |path| File.read(path, encoding: Encoding::UTF_8) }.join("\n")
+      include_system = !@config.ignore_system_fonts
+      missing = Fonts.missing(combined, @config.font_paths, include_system: include_system)
+      return if missing.empty?
+
+      raise FontMissingError.new(missing, Fonts.search_paths(@config.font_paths)) if @config.strict_fonts
+
+      @config.on_warning&.call(
+        missing.map { |family| "unknown font family: #{family.inspect} (substituted)" },
+        @template
+      )
+    end
+  end
+end

data/lib/typstify/engine.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Typstify
+  # Wires the gem into a Rails application: the `pdf` renderer, sensible
+  # defaults taken from the app, and the rake tasks.
+  class Engine < ::Rails::Engine
+    isolate_namespace Typstify
+
+    # Generators live in this gem, not the host app.
+    config.app_generators.templates.unshift(File.expand_path("../generators", __dir__))
+
+    initializer "typstify.renderer" do
+      ActiveSupport.on_load(:action_controller) do
+        require "typstify/renderer"
+        Typstify::Renderer.install!
+      end
+    end
+
+    initializer "typstify.defaults" do |app|
+      unless Typstify.config.instance_variable_get(:@template_root)
+        Typstify.config.template_root = app.root.join("app/views")
+      end
+    end
+
+    # Applied after the host's initializers have had their say, so a
+    # package_cache set in config/initializers/typstify.rb is honoured.
+    config.after_initialize do
+      Typstify.apply_package_cache!
+    end
+
+    # No `rake_tasks do load … end` here: Rails::Engine already loads every
+    # .rake file under the engine's lib/tasks. Loading it again re-opens the
+    # task and Rake *appends* the second body, so `typstify:preview` would
+    # render — and announce — the same PDF twice.
+  end
+end

data/lib/typstify/erb_pipeline.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Typstify
+  # ERB mode: `.typ.erb` templates are ordinary ERB whose *output* is Typst
+  # source. Provided for teams migrating from wicked_pdf who want their existing
+  # view habits; data mode is the one to reach for.
+  #
+  # The distinction that matters: in data mode a user string is data all the way
+  # down and cannot change the document. Here it is spliced into source, so
+  # every dynamic value must go through `typ()`. That is not a style preference
+  # — an unescaped value is code injection.
+  module ErbPipeline
+    # The object templates are evaluated against. Deliberately small: `typ`,
+    # `data`, and whatever instance variables the controller had.
+    class Context
+      def initialize(data:, assigns: {})
+        @data = data
+        assigns.each { |name, value| instance_variable_set(:"@#{name}", value) }
+      end
+
+      # The data hash passed to `render pdf:` / `Typstify.render`.
+      attr_reader :data
+
+      # Escape a value so Typst renders it literally. See Typstify::Escaping.
+      def typ(value)
+        Escaping.typ(value)
+      end
+
+      def template_binding
+        binding
+      end
+    end
+
+    module_function
+
+    # @return [String] Typst source
+    def render(source, data: nil, assigns: {})
+      context = Context.new(data: data, assigns: assigns)
+      ERB.new(source, trim_mode: "-").result(context.template_binding)
+    end
+  end
+end

data/lib/typstify/errors.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Typstify
+  # Base class for everything this gem raises. Rescue this to catch any
+  # Typstify failure without also swallowing unrelated errors.
+  class Error < StandardError; end
+
+  # The template could not be found as either `.typ` or `.typ.erb`.
+  class MissingTemplate < Error
+    attr_reader :template, :tried
+
+    def initialize(template, tried)
+      @template = template
+      @tried = tried
+      super(<<~MSG.strip)
+        Could not find a Typst template for #{template.inspect}.
+
+        Tried:
+        #{tried.map { |p| "  - #{p}" }.join("\n")}
+
+        Templates live under Typstify.config.template_root
+        (#{Typstify.config.template_root}).
+      MSG
+    end
+  end
+
+  # A template path resolved outside `template_root`, or a workspace copy tried
+  # to escape its root. Always a bug or an attack; never a normal condition.
+  class PathError < Error; end
+
+  # The Typst compiler rejected the document. Carries the compiler's own
+  # annotated diagnostic, which points at the offending line.
+  class CompileError < Error
+    attr_reader :template, :typst_message, :line, :column
+
+    def initialize(template:, typst_message:, line: nil, column: nil)
+      @template = template
+      @typst_message = typst_message
+      @line = line
+      @column = column
+      location = line ? " (line #{line}#{", column #{column}" if column})" : ""
+      super("Typst failed to compile #{template}#{location}:\n\n#{typst_message}")
+    end
+  end
+
+  # A font family a template asks for is not installed and is not in any
+  # configured `font_paths`. Raised only when `strict_fonts` is on.
+  class FontMissingError < Error
+    attr_reader :families
+
+    def initialize(families, searched)
+      @families = families
+      super(<<~MSG.strip)
+        Missing font #{families.size == 1 ? "family" : "families"}: #{families.map(&:inspect).join(", ")}
+
+        Typst would silently substitute a different face, which changes your
+        layout without telling you. Vendor the font and add its directory:
+
+            Typstify.configure { |c| c.font_paths = [Rails.root.join("app/assets/fonts")] }
+
+        Searched:
+        #{searched.map { |p| "  - #{p}" }.join("\n")}
+
+        Set `c.strict_fonts = false` to downgrade this to a warning.
+      MSG
+    end
+  end
+end

data/lib/typstify/escaping.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Typstify
+  # Escaping for ERB mode (`.typ.erb`).
+  #
+  # In data mode this file is irrelevant: values arrive as JSON and Typst reads
+  # them as strings, so they can never become code. ERB mode splices Ruby
+  # strings straight into Typst *source*, which means an unescaped value is
+  # code injection — Typst can read files and run script inside its root.
+  #
+  # `typ()` renders any value as literal text by backslash-escaping every
+  # character Typst treats as markup.
+  module Escaping
+    # Order matters only for the backslash, which has to go first so the
+    # backslashes introduced below are not escaped a second time.
+    SIGNIFICANT = [
+      "\\",
+      "#",  # code / function call
+      "*",  # strong
+      "_",  # emphasis
+      "`",  # raw
+      "$",  # math
+      "@",  # reference / package
+      "<",  # label open
+      ">",  # label close
+      "[",  # content block open
+      "]",  # content block close
+      '"'   # string delimiter in code context
+    ].freeze
+
+    PATTERN = Regexp.union(SIGNIFICANT).freeze
+
+    module_function
+
+    # Escape a value so Typst renders it as literal text.
+    #
+    #   typ('#read("/etc/passwd")') # => '\#read\("/etc/passwd"\)' — printed, not run
+    #
+    # @param value [Object] anything; converted with #to_s
+    # @return [String] Typst source that renders as the original text
+    def typ(value)
+      value.to_s.gsub(PATTERN) { |char| "\\#{char}" }
+    end
+  end
+end