typstify 0.1.0

data/lib/typstify/fonts.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "set"
+
+module Typstify
+  # Font resolution, done by us rather than by the compiler.
+  #
+  # Typst warns about an unknown font family and then quietly substitutes
+  # another face — which is how a production invoice ends up in a font nobody
+  # chose. We would rather surface that, but the `typst` binding currently
+  # discards compiler warnings on a successful compile (it only formats them
+  # into the message when compilation *fails*), so there is nothing to listen
+  # to. See the upstream PR linked in the README.
+  #
+  # Until that lands, we answer the question ourselves: read the family names a
+  # template asks for out of its source, and check them against the fonts we
+  # can actually see. Cheap, deterministic, and honest about what it covers —
+  # it reads static `font:` declarations, not families computed at runtime.
+  module Fonts
+    # Faces compiled into the Typst binary; always available, never on disk.
+    EMBEDDED = [
+      "libertinus serif",
+      "new computer modern",
+      "new computer modern math",
+      "deja vu sans mono",
+      "dejavu sans mono"
+    ].freeze
+
+    # `font: "Inter"` or `font: ("Inter", "Noto Sans")`
+    DECLARATION = /\bfont\s*:\s*(\((?:[^()]*)\)|"(?:[^"\\]|\\.)*")/m
+    STRING = /"((?:[^"\\]|\\.)*)"/
+
+    SYSTEM_DIRECTORIES = [
+      "/System/Library/Fonts",
+      "/System/Library/Fonts/Supplemental",
+      "/Library/Fonts",
+      "~/Library/Fonts",
+      "/usr/share/fonts",
+      "/usr/local/share/fonts",
+      "~/.fonts",
+      "~/.local/share/fonts"
+    ].freeze
+
+    EXTENSIONS = %w[.ttf .otf .ttc .otc].freeze
+
+    module_function
+
+    # Families a chunk of Typst source asks for, in declaration order.
+    def declared_families(source)
+      source.to_s.scan(DECLARATION).flat_map do |(declaration)|
+        declaration.scan(STRING).flatten
+      end.map(&:strip).reject(&:empty?).uniq
+    end
+
+    # Families the compiler will be able to find, downcased for comparison.
+    def available_families(font_paths, include_system: true)
+      key = [font_paths.map(&:to_s).sort, include_system]
+      @available ||= {}
+      @available[key] ||= begin
+        families = EMBEDDED.dup
+        search_paths(font_paths, include_system: include_system).each do |directory|
+          families.concat(families_in(directory))
+        end
+        families.map(&:downcase).uniq.to_set
+      end
+    end
+
+    # Reset the memoized scan. Fonts installed mid-process are rare; specs are not.
+    def reset!
+      @available = nil
+    end
+
+    # @return [Array<String>] families the template wants and nothing provides
+    def missing(source, font_paths, include_system: true)
+      available = available_families(font_paths, include_system: include_system)
+      declared_families(source).reject { |family| available.include?(family.downcase) }
+    end
+
+    # The directories the compiler will look in. Kept in step with
+    # `ignore_system_fonts`, so the check never calls a family available that
+    # the compiler will not actually reach for.
+    def search_paths(font_paths, include_system: true)
+      paths = font_paths.map { |path| File.expand_path(path.to_s) }
+      paths += SYSTEM_DIRECTORIES.map { |directory| File.expand_path(directory) } if include_system
+      paths
+    end
+
+    def families_in(directory)
+      return [] unless File.directory?(directory)
+
+      Dir.glob(File.join(directory, "**", "*")).flat_map do |path|
+        next [] unless EXTENSIONS.include?(File.extname(path).downcase)
+
+        read_families(path)
+      end
+    rescue SystemCallError
+      []
+    end
+
+    # Family names out of an SFNT `name` table (nameID 1 and 16).
+    def read_families(path)
+      File.open(path, "rb") do |file|
+        header = file.read(4)
+        return [] if header.nil?
+
+        offsets = header == "ttcf" ? collection_offsets(file) : [0]
+        offsets.flat_map { |offset| families_at(file, offset) }
+      end
+    rescue SystemCallError, EOFError
+      []
+    end
+
+    def collection_offsets(file)
+      file.seek(8)
+      count = file.read(4).unpack1("N")
+      return [] if count.nil? || count.zero? || count > 1024
+
+      Array(file.read(4 * count)&.unpack("N*"))
+    end
+
+    def families_at(file, base)
+      file.seek(base + 4)
+      table_count = file.read(2)&.unpack1("n")
+      return [] if table_count.nil? || table_count.zero?
+
+      file.seek(base + 12)
+      records = file.read(16 * table_count).to_s
+      name_offset = nil
+      table_count.times do |index|
+        record = records[index * 16, 16]
+        break if record.nil?
+
+        name_offset = record[8, 4].unpack1("N") if record[0, 4] == "name"
+      end
+      return [] if name_offset.nil?
+
+      parse_name_table(file, name_offset)
+    end
+
+    def parse_name_table(file, offset)
+      file.seek(offset)
+      header = file.read(6)
+      return [] if header.nil? || header.bytesize < 6
+
+      _format, count, storage = header.unpack("n3")
+      records = file.read(12 * count).to_s
+
+      count.times.filter_map do |index|
+        record = records[index * 12, 12]
+        next if record.nil?
+
+        platform, _encoding, _language, name_id, length, string_offset = record.unpack("n6")
+        next unless [1, 16].include?(name_id)
+
+        file.seek(offset + storage + string_offset)
+        decode(file.read(length), platform)
+      end.compact.uniq
+    end
+
+    def decode(bytes, platform)
+      return nil if bytes.nil? || bytes.empty?
+
+      string =
+        if platform == 3 || platform.zero?
+          bytes.force_encoding(Encoding::UTF_16BE).encode(Encoding::UTF_8)
+        else
+          bytes.force_encoding(Encoding::BINARY).encode(Encoding::UTF_8, Encoding::ISO_8859_1)
+        end
+      string.strip.empty? ? nil : string.strip
+    rescue EncodingError
+      nil
+    end
+  end
+end

data/lib/typstify/renderer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "action_controller"
+
+module Typstify
+  # Registers `render pdf:` on every controller.
+  #
+  #   render pdf: "invoices/show",
+  #          data: { number: "A-1" },
+  #          filename: "invoice-A-1.pdf",
+  #          disposition: :inline
+  #
+  # `filename` defaults to the template's basename; `disposition` to attachment,
+  # matching `send_data`.
+  module Renderer
+    DEFAULT_DISPOSITION = :attachment
+
+    def self.install!
+      ActionController::Renderers.add :pdf do |template, options|
+        pdf = Typstify.render(
+          template: template,
+          data: options[:data],
+          assigns: view_assigns
+        )
+
+        send_data(
+          pdf,
+          type: options[:type] || "application/pdf",
+          filename: Typstify::Renderer.filename_for(template, options),
+          disposition: options[:disposition] || DEFAULT_DISPOSITION,
+          status: options[:status] || :ok
+        )
+      end
+    end
+
+    def self.filename_for(template, options)
+      return options[:filename] if options[:filename]
+
+      base = File.basename(template.to_s).sub(/\.typ(\.erb)?\z/, "")
+      "#{base}.pdf"
+    end
+  end
+end

data/lib/typstify/resolver.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Typstify
+  # Turns a template name ("invoices/show") into a file on disk, and refuses to
+  # look outside `template_root` while doing it.
+  #
+  # This is the first of two containment layers. The second — and the one that
+  # actually matters — is the workspace: Typst compiles with the tmpdir as its
+  # root, so even a template that somehow got resolved elsewhere could not read
+  # past it. This layer exists to turn a traversal attempt into a clear error
+  # rather than a confusing "file not found".
+  class Resolver
+    Resolution = Struct.new(:name, :path, :mode, keyword_init: true) do
+      def erb? = mode == :erb
+    end
+
+    # Data mode wins: a directory holding both show.typ and show.typ.erb
+    # renders the safe one.
+    EXTENSIONS = { ".typ" => :data, ".typ.erb" => :erb }.freeze
+
+    def initialize(config = Typstify.config)
+      @config = config
+    end
+
+    # @param name [String] e.g. "invoices/show", with or without extension
+    # @return [Resolution]
+    # @raise [PathError] if the name points outside template_root
+    # @raise [MissingTemplate] if nothing is there
+    def call(name)
+      stem = name.to_s.sub(/\.typ(\.erb)?\z/, "")
+      root = @config.template_root.expand_path
+
+      tried = EXTENSIONS.keys.map { |ext| candidate(root, stem, ext) }
+
+      EXTENSIONS.each_with_index do |(_ext, mode), index|
+        path = tried[index]
+        return Resolution.new(name: stem, path: path, mode: mode) if path.file?
+      end
+
+      raise MissingTemplate.new(name, tried)
+    end
+
+    private
+
+    def candidate(root, stem, extension)
+      if stem.start_with?("/", "~")
+        raise PathError, "Template name #{stem.inspect} must be relative to template_root (#{root})."
+      end
+
+      path = root.join("#{stem}#{extension}").expand_path
+      unless path.to_s == root.to_s || path.to_s.start_with?("#{root}#{File::SEPARATOR}")
+        raise PathError,
+              "Template name #{stem.inspect} resolves to #{path}, which is outside " \
+              "template_root (#{root}). Path traversal is not allowed."
+      end
+
+      path
+    end
+  end
+end

data/lib/typstify/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Typstify
+  VERSION = "0.1.0"
+end

data/lib/typstify/warnings.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Typstify
+  # Parsing for the compiler's diagnostic output.
+  #
+  # The binding gives us diagnostics as one formatted blob — the same codespan
+  # rendering the `typst` CLI prints — raised as an ArgumentError:
+  #
+  #   error: expected expression
+  #     ┌─ /tmp/typstify-abc/main.typ:12:8
+  #     │
+  #  12 │ #let x =
+  #     │         ^
+  #
+  # Warnings share that format and are included *only when compilation fails*,
+  # so a successful compile with warnings tells us nothing. Everything here is
+  # therefore best-effort presentation, not a contract.
+  module Warnings
+    BLOCK = /^(?<severity>error|warning):\s*(?<message>.*)$/
+    LOCATION = /┌─\s*(?<path>.+?):(?<line>\d+):(?<column>\d+)/
+
+    Diagnostic = Struct.new(:severity, :message, :line, :column, keyword_init: true)
+
+    module_function
+
+    # Split a raw diagnostic blob into its individual errors and warnings.
+    def parse(raw)
+      text = raw.to_s
+      starts = text.enum_for(:scan, BLOCK).map { Regexp.last_match.begin(0) }
+      return [] if starts.empty?
+
+      bounds = starts.zip(starts.drop(1) + [text.length])
+      bounds.map do |(from, to)|
+        chunk = text[from...to]
+        header = chunk.match(BLOCK)
+        location = chunk.match(LOCATION)
+        Diagnostic.new(
+          severity: header[:severity].to_sym,
+          message: header[:message].strip,
+          line: location && location[:line].to_i,
+          column: location && location[:column].to_i
+        )
+      end
+    end
+
+    # The workspace is a tmpdir with a random name; showing it to a developer
+    # who wrote `app/views/invoices/show.typ` is noise at best. Swap it for the
+    # name they used.
+    def rewrite_paths(raw, workspace_dir, template_name)
+      raw.to_s
+         .gsub(%r{#{Regexp.escape(workspace_dir.to_s)}/?main\.typ}, "#{template_name}.typ")
+         .gsub(%r{#{Regexp.escape(workspace_dir.to_s)}/?}, "")
+         .gsub(%r{[^\s:]*/main\.typ}, "#{template_name}.typ")
+    end
+
+    def dispatch(diagnostics, template, config)
+      messages = diagnostics.select { |d| d.severity == :warning }.map do |diagnostic|
+        diagnostic.line ? "#{diagnostic.message} (line #{diagnostic.line})" : diagnostic.message
+      end
+      return if messages.empty?
+
+      config.on_warning&.call(messages, template)
+    end
+  end
+end

data/lib/typstify/workspace.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require "pathname"
+
+module Typstify
+  # A throwaway directory holding everything one compile is allowed to see.
+  #
+  #   <tmp>/main.typ      the template
+  #   <tmp>/data.json     your data
+  #   <tmp>/shared/       config.shared_dir, copied
+  #
+  # Typst is invoked with this directory as its root, so `#read("../.env")`
+  # cannot reach your application — not because we filter it, but because the
+  # file is not there. That is the whole security model, and it is why the
+  # template is copied to the *root* of the workspace rather than nested: Typst
+  # resolves relative imports against the importing file, so main-at-root is
+  # what makes `#import "shared/branding.typ"` work from any view subdirectory.
+  #
+  # Every render gets its own workspace, which is also what makes concurrent
+  # rendering safe.
+  class Workspace
+    MAIN = "main.typ"
+    DATA = "data.json"
+
+    attr_reader :dir
+
+    # Yields a Workspace and removes it afterwards, exception or not.
+    def self.build(source:, data:, config: Typstify.config)
+      Dir.mktmpdir("typstify-") do |tmp|
+        workspace = new(Pathname.new(tmp), config)
+        workspace.write_main(source)
+        workspace.write_data(data)
+        workspace.copy_shared
+        yield workspace
+      end
+    end
+
+    def initialize(dir, config)
+      @dir = dir
+      @config = config
+    end
+
+    def main_path = dir.join(MAIN)
+
+    def write_main(source)
+      File.write(main_path, source, encoding: Encoding::UTF_8)
+    end
+
+    # Takes the already-serialised JSON string: validation happens in Document,
+    # before a workspace exists.
+    def write_data(data)
+      File.write(dir.join(DATA), data || "{}", encoding: Encoding::UTF_8)
+    end
+
+    # Copy config.shared_dir in, if it exists. Copies rather than symlinks:
+    # a symlink inside the root points outside the root, which would hand back
+    # exactly the file-system access the workspace exists to remove. Symlinks
+    # found in the source tree are skipped for the same reason.
+    def copy_shared
+      source = @config.template_root.join(@config.shared_dir)
+      return unless source.directory?
+
+      destination = dir.join(@config.shared_dir)
+      copy_tree(source, destination)
+    end
+
+    private
+
+    def copy_tree(source, destination)
+      FileUtils.mkdir_p(destination)
+      source.children.each do |child|
+        next if child.symlink?
+
+        target = destination.join(child.basename)
+        if child.directory?
+          copy_tree(child, target)
+        elsif child.file?
+          FileUtils.cp(child, target)
+        end
+      end
+    end
+  end
+end

data/lib/typstify.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "stringio"
+
+require_relative "typstify/version"
+require_relative "typstify/errors"
+require_relative "typstify/config"
+require_relative "typstify/escaping"
+require_relative "typstify/data"
+require_relative "typstify/warnings"
+require_relative "typstify/fonts"
+require_relative "typstify/resolver"
+require_relative "typstify/workspace"
+require_relative "typstify/erb_pipeline"
+require_relative "typstify/adapter"
+require_relative "typstify/document"
+
+require_relative "typstify/engine" if defined?(Rails::Engine)
+
+# PDF generation for Rails on the Typst engine.
+#
+#   Typstify.render(template: "invoices/show", data: { number: "A-1" })
+#
+# In a controller, prefer the renderer:
+#
+#   render pdf: "invoices/show", data: { ... }, filename: "invoice.pdf"
+module Typstify
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+      apply_package_cache!
+      config
+    end
+
+    # Mostly for specs: drop all configuration and cached font scans.
+    def reset!
+      @config = Config.new
+      Fonts.reset!
+      config
+    end
+
+    # Compile a template to PDF.
+    #
+    # @param template [String] e.g. "invoices/show"
+    # @param data [Object] anything JSON-serializable; read in the template
+    #   with `#let data = json("data.json")`
+    # @param assigns [Hash] instance variables for ERB mode only
+    # @return [String] PDF bytes, ASCII-8BIT
+    def render(template:, data: nil, assigns: {})
+      Document.new(template: template, data: data, assigns: assigns, config: config).to_pdf
+    end
+
+    # Render and attach in one step.
+    #
+    #   Typstify.render_and_attach(user.documents,
+    #                              template: "certificates/completion",
+    #                              data: cert_data, filename: "certificate.pdf")
+    #
+    # @param attachable [#attach] an ActiveStorage has_one/has_many attachment proxy
+    def render_and_attach(attachable, template:, filename:, data: nil, assigns: {},
+                          content_type: "application/pdf")
+      pdf = render(template: template, data: data, assigns: assigns)
+      attachable.attach(
+        io: StringIO.new(pdf),
+        filename: filename,
+        content_type: content_type
+      )
+    end
+
+    def root
+      @root ||= Pathname.new(__dir__).join("..").expand_path
+    end
+
+    # Faces shipped with the gem, always on the font search path so the starter
+    # templates render with no configuration.
+    def bundled_font_path
+      root.join("fonts")
+    end
+
+    # The starter template pack, copied by `rails g typstify:template`.
+    def template_pack_path
+      root.join("templates")
+    end
+
+    # Point Typst's package resolution at the configured cache.
+    #
+    # Typst looks in the platform data directory, which on Linux — and so in
+    # every Docker image — is XDG_DATA_HOME. Set once at boot rather than around
+    # each compile, because mutating ENV per render is not thread-safe and
+    # concurrent rendering is a supported use. On macOS the platform directory
+    # is fixed and this has no effect; see docs/fonts-and-docker.md.
+    def apply_package_cache!
+      cache = config.package_cache
+      return if cache.nil?
+
+      ENV["XDG_DATA_HOME"] = cache.expand_path.to_s
+    end
+  end
+end

data/templates/certificate/certificate.typ

@@ -0,0 +1,70 @@
+// Certificate — Typstify starter template.
+//
+// Landscape, centred, and deliberately restrained: a border, a name, a reason.
+// Data mode; see templates/invoice for the fuller commentary.
+
+#import "shared/branding.typ": *
+
+#let data = json("data.json")
+
+#set page(
+  paper: "a4",
+  flipped: true,
+  margin: 16mm,
+  background: {
+    place(center + horizon, rect(
+      width: 100% - 10mm,
+      height: 100% - 10mm,
+      stroke: 1.5pt + brand.accent,
+      radius: 2pt,
+    ))
+    place(center + horizon, rect(
+      width: 100% - 14mm,
+      height: 100% - 14mm,
+      stroke: 0.5pt + brand.rule,
+    ))
+  },
+)
+#set text(font: brand.font, size: 11pt, fill: brand.ink)
+
+#align(center)[
+  #v(14mm)
+  #text(size: 9pt, fill: brand.muted, tracking: 2pt)[#upper(data.at("eyebrow", default: "Certificate"))]
+
+  #v(6mm)
+  #text(size: 30pt, weight: "semibold", fill: brand.accent)[#data.title]
+
+  #v(8mm)
+  #text(size: 10pt, fill: brand.muted)[#data.presented_to_label]
+
+  #v(3mm)
+  #text(size: 26pt, weight: "semibold")[#data.recipient]
+
+  #v(3mm)
+  #line(length: 70mm, stroke: 0.5pt + brand.rule)
+
+  #v(6mm)
+  #block(width: 60%)[
+    #set par(justify: false, leading: 0.8em)
+    #text(size: 11pt, fill: brand.muted)[#data.description]
+  ]
+
+  #v(14mm)
+
+  #grid(
+    columns: (1fr, 1fr),
+    gutter: 30mm,
+    ..data.signatories.map(person => [
+      #line(length: 100%, stroke: 0.5pt + brand.ink)
+      #v(2pt)
+      #text(size: 10pt, weight: "semibold")[#person.name]
+      #linebreak()
+      #text(size: 8.5pt, fill: brand.muted)[#person.role]
+    ]),
+  )
+
+  #v(8mm)
+  #text(size: 8pt, fill: brand.muted)[
+    #data.issued_on #h(6pt) · #h(6pt) #data.reference
+  ]
+]

data/templates/certificate/sample_data.json

@@ -0,0 +1,13 @@
+{
+  "eyebrow": "Certificate of Completion",
+  "title": "Advanced Rails Performance",
+  "presented_to_label": "This is to certify that",
+  "recipient": "Ada Okonkwo",
+  "description": "has successfully completed the twelve-week programme covering query optimisation, caching strategy, background processing and production profiling, including all assessed exercises.",
+  "signatories": [
+    { "name": "Priya Raman", "role": "Programme Director" },
+    { "name": "Tom Whelan", "role": "Lead Instructor" }
+  ],
+  "issued_on": "18 June 2026",
+  "reference": "Certificate no. CRT-00412"
+}

data/templates/invoice/invoice.typ

@@ -0,0 +1,57 @@
+// Invoice — Typstify starter template.
+//
+// Data mode: every dynamic value arrives as JSON. Nothing here interpolates a
+// Ruby string into source, so a customer named `#read("/etc/passwd")` renders
+// as those characters and nothing else.
+//
+// Preview it without booting Rails:
+//   rake typstify:preview[invoices/show]
+
+#import "shared/branding.typ": *
+
+#let data = json("data.json")
+
+#show: brand-page
+
+#brand-header(
+  title: "Invoice " + data.number,
+  subtitle: data.at("subtitle", default: none),
+  meta: (
+    ("Issued", data.issued_on),
+    ("Due", data.due_on),
+    ("Amount due", data.total),
+  ),
+)
+
+#grid(
+  columns: (1fr, 1fr),
+  gutter: 16pt,
+  brand-address(label: "Billed to", lines: data.bill_to),
+  brand-address(label: "From", lines: data.bill_from),
+)
+
+#v(14pt)
+
+#brand-table(
+  columns: (1fr, auto, auto, auto),
+  aligns: (left, right, right, right),
+  header: ("Description", "Qty", "Unit", "Amount"),
+  rows: data.line_items.map(item => (
+    [#item.name],
+    [#item.qty],
+    [#item.unit_price],
+    [#item.amount],
+  )),
+)
+
+#v(12pt)
+
+#brand-totals(
+  rows: data.at("summary", default: ()).map(row => (row.label, row.value)),
+  emphasis: ("Total due", data.total),
+)
+
+#if data.at("notes", default: none) != none [
+  #v(16pt)
+  #brand-note[#data.notes]
+]