bitgram 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 96c030724c346e56e13df01f92afcb6be7c1a332cdc539dc31fa23566fafbd07
+  data.tar.gz: 675314177dd5e9ecd8a877a56308376d321de8a9cf793fc6bfda32509e48715e
+SHA512:
+  metadata.gz: cfaed2259b457c9a95c0ec4fe883e7d48395c86c5b806447bebcc0af148b499ae9dbfeab204607f2b9c9cfe25a90e6284e493840589ff5116d0a5e6079e841c2
+  data.tar.gz: a0492e8a7f993cfe645059811663e3edb9892689c7a9490b0527417431e86d4f991ad3716bb55dfaa01148b6fad2b53a13d4041db07ff57d1f53d85823d58ffd

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-29
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,118 @@
+# Bitgram
+
+Generate packet headers, bit fields, and register maps from YAML, JSON, or Ruby. One layout produces RFC-style ASCII, Unicode box drawings, SVG, PNG, and JPEG.
+
+```text
+ 0                   1                   2                   3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|          Source Port          |       Destination Port        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|            Length             |           Checksum            |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+.                                                               .
+.                             Data                              .
+.                                                               .
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+<img src="examples/tcp.svg" alt="TCP header showing ports, sequence numbers, flags, and variable-length data">
+
+## Installation
+
+Requires Ruby 3.3 or later. ASCII and SVG need only the `unicode-display_width` runtime gem.
+
+For a source checkout:
+
+```sh
+bundle install
+bundle exec rake install
+```
+
+Once published on RubyGems:
+
+```sh
+gem install bitgram
+```
+
+PNG and JPEG need an optional converter. For the preferred vips backend, add `gem "ruby-vips", "~> 2.3"` to your application's Gemfile and install libvips:
+
+```sh
+# macOS
+brew install vips librsvg imagemagick
+# Ubuntu
+sudo apt-get install libvips-dev librsvg2-bin imagemagick fonts-noto-cjk
+```
+
+Any one supported converter suffices. `rsvg-convert` supports PNG; vips and ImageMagick support PNG and JPEG. Automatic selection tries vips, rsvg, then ImageMagick. Run `bitgram doctor` to inspect availability and Japanese fonts.
+
+## Quick start
+
+Save this as `udp.yml`:
+
+```yaml
+version: 1
+title: UDP Header
+fields:
+  - { name: Source Port, bits: 16 }
+  - { name: Destination Port, bits: 16 }
+  - { name: Length, bits: 16 }
+  - { name: Checksum, bits: 16 }
+  - { name: Data, bits: variable }
+```
+
+```sh
+bitgram render udp.yml
+bitgram render udp.yml -o udp.svg
+bitgram render udp.yml -o udp.png --scale 2
+bitgram render --preset tcp --ascii-style unicode
+bitgram init ipv6 > ipv6.yml
+bitgram validate udp.yml --strict
+```
+
+Set `layout.row_bits` for a width other than 32 bits, `layout.bit_order: lsb0` for register numbering, and `layout.offsets: hex` for byte offsets. Fields can use `bytes`, a `short` label, `reserved`, `optional`, and `fill`. See the [format reference](docs/format.md) and [CLI reference](docs/cli.md).
+
+## Ruby API
+
+```ruby
+require "bitgram"
+
+diagram = Bitgram.load_file("udp.yml")
+puts diagram.to_ascii(style: :unicode)
+diagram.save("udp.svg", theme: "dark")
+diagram.save("udp.jpg", scale: 2, quality: 85)
+
+register = Bitgram.define(title: "CTRL") do
+  row_bits 16
+  bit_order :lsb0
+  field "EN", bits: 1, description: "Enable"
+  field "MODE", bits: 3
+  reserved 4
+  field "DIV", bits: 8
+end
+puts register.to_ascii
+```
+
+The [Ruby API guide](docs/ruby-api.md) covers diagnostics, overrides, and inspecting the shared layout. [Preset sources](docs/presets.md) document the six bundled protocol definitions.
+
+## Rendering notes
+
+- ASCII uses display widths for Japanese text. Unicode border characters are East Asian Ambiguous: terminals configured to render them as two columns will misalign the borders. Use RFC style or set your terminal's ambiguous width to one.
+- PNG/JPEG rendering uses installed fonts. Install a CJK font such as Noto Sans CJK JP for Japanese labels. `bitgram doctor` checks fontconfig when available.
+- SVG text measurement estimates font width. Increase `svg.char_width_ratio` or use a monospace font if your chosen font extends beyond a cell.
+- YAML aliases and object tags are rejected. Definitions are limited to 1 MiB, 10,000 fields, and 4,096 logical rows; raster output is limited to 50 million pixels. Definitions never cause network requests.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake examples
+bundle exec yard doc
+```
+
+Enable raster development dependencies with `bundle config set --local with raster`, then run `bundle install`. Raster integration tests skip converters unavailable on the machine; the dedicated CI job installs all three backends. See [release procedures](docs/releasing.md) for publishing setup.
+
+## License
+
+[MIT](LICENSE.txt).

data/exe/bitgram

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bitgram"
+
+exit Bitgram::CLI.new.run(ARGV)

data/lib/bitgram/cli/doctor.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # @api private
+  class CLI
+    private
+
+    def doctor
+      @stdout.puts("Ruby          #{RUBY_VERSION}\nbitgram       #{VERSION}")
+      labels = { vips: "vips", rsvg: "rsvg-convert", imagemagick: "ImageMagick" }
+      Rasterizers::Registry.all.each do |name, converter|
+        state = converter.available? ? "available (#{converter.version})" : "not found"
+        @stdout.puts("#{labels.fetch(name).ljust(14)}#{state}")
+      end
+      @stdout.puts("CJK font      #{cjk_fonts}")
+      selections = %i[png jpeg].map do |format|
+        "#{format}: #{Rasterizers::Registry.select(:auto, format: format, timeout: 30).name}"
+      rescue RasterizerNotFound
+        "#{format}: unavailable"
+      end
+      @stdout.puts("=> #{selections.join(', ')}")
+    end
+
+    def cjk_fonts
+      executable = Util::Command.which("fc-list")
+      return "unknown (fc-list not installed)" unless executable
+
+      fonts = Util::Command.run([executable, ":lang=ja", "family"], stdin_data: "", timeout: 5)
+      fonts.strip.empty? ? "not found" : "found (#{fonts.lines.first.strip})"
+    rescue RasterizeError
+      "unknown (fontconfig failed)"
+    end
+  end
+end

data/lib/bitgram/cli/options.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # @api private
+  class CLI
+    private
+
+    def parser_for(command, options)
+      OptionParser.new do |parser|
+        parser.banner = "Usage: bitgram #{command} #{command == 'validate' ? 'INPUT...' : '[options]'}"
+        parser.on("-h", "--help", "Show help") { options[:help] = true }
+        parser.on("--debug", "Show failure backtraces") { @debug = true }
+        next unless %w[render validate].include?(command)
+
+        parser.on("--strict", "Treat warnings as errors") { options[:strict] = true }
+        parser.on("--input-format FORMAT", %w[yaml json], "Input format") do |value|
+          options[:input_format] = value.to_sym
+        end
+        render_options(parser, options) if command == "render"
+      end
+    end
+
+    def render_options(parser, options)
+      parser.on("-f", "--format FORMAT", %w[ascii svg png jpeg]) { |value| options[:format] = value }
+      parser.on("-o", "--output PATH") { |value| options[:output] = value }
+      parser.on("--preset NAME") { |value| options[:preset] = value }
+      {
+        "--row-bits N" => ["layout.row_bits", Integer], "--bit-order ORDER" => ["layout.bit_order", String],
+        "--ascii-style STYLE" => ["ascii.style", String], "--theme NAME_OR_PATH" => ["svg.theme", String],
+        "--scale N" => ["raster.scale", Float], "--rasterizer NAME" => ["raster.rasterizer", String]
+      }.each do |flag, (key, type)|
+        parser.on(flag, type) { |value| assign(options[:overrides], key, value) }
+      end
+      parser.on("--set KEY=VALUE") do |value|
+        key, raw = value.split("=", 2)
+        raise OptionParser::InvalidArgument, "--set requires KEY=VALUE" unless raw
+
+        assign(options[:settings], key, parse_value(raw))
+      end
+    end
+
+    def assign(target, key, value)
+      parts = key.split(".", -1)
+      unless parts.all? { |part| /\A[a-z_]+\z/.match?(part) }
+        raise OptionParser::InvalidArgument, "invalid setting key: #{key}"
+      end
+
+      leaf = parts.pop
+      parts.each do |part|
+        target[part] ||= {}
+        raise OptionParser::InvalidArgument, "conflicting setting key: #{key}" unless target[part].is_a?(Hash)
+
+        target = target[part]
+      end
+      target[leaf] = value
+    end
+
+    def parse_value(value)
+      return value == "true" if %w[true false].include?(value)
+      return value.to_i if /\A-?\d+\z/.match?(value)
+      return value.to_f if /\A-?\d+\.\d+\z/.match?(value)
+
+      value
+    end
+  end
+end

data/lib/bitgram/cli.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "rasterizers/registry"
+
+module Bitgram
+  # @api private
+  class CLI
+    COMMANDS = %w[render validate presets init doctor version].freeze
+    FORMATS = { ".txt" => "ascii", ".svg" => "svg", ".png" => "png", ".jpg" => "jpeg", ".jpeg" => "jpeg" }.freeze
+
+    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run(argv)
+      args = argv.dup
+      @debug = args.delete("--debug")
+      return help if %w[-h --help].include?(args.first)
+      return version if %w[-v --version].include?(args.first)
+
+      execute(args)
+    rescue ValidationError => e
+      report_issues(e.issues, @input_name)
+      1
+    rescue ParseError, LayoutError, RenderError => e
+      failure(e, 1)
+    rescue OptionParser::ParseError, ArgumentError => e
+      failure(e, 2)
+    rescue RasterizeError => e
+      failure(e, 3)
+    rescue SystemCallError, IOError => e
+      failure(e, 4)
+    rescue StandardError => e
+      failure(e, 70)
+    end
+
+    private
+
+    def execute(args)
+      command = args.shift
+      raise OptionParser::InvalidArgument, "expected #{COMMANDS.join(', ')}" unless COMMANDS.include?(command)
+
+      options = { overrides: {}, settings: {} }
+      parser = parser_for(command, options)
+      parser.parse!(args)
+      return @stdout.puts(parser) || 0 if options[:help]
+
+      dispatch(command, args, options)
+    end
+
+    def help
+      @stdout.puts("Usage: bitgram <command> [options]\n\nCommands: #{COMMANDS.join(', ')}")
+      0
+    end
+
+    def version
+      @stdout.puts(VERSION)
+      0
+    end
+
+    def dispatch(command, args, options)
+      case command
+      when "render" then return render(args, options)
+      when "validate" then return validate(args, options)
+      when "init" then return init(args)
+      end
+
+      simple_command(command, args)
+    end
+
+    def simple_command(command, args)
+      raise OptionParser::InvalidArgument, "unexpected arguments: #{args.join(' ')}" unless args.empty?
+
+      case command
+      when "presets" then @stdout.puts(Bitgram.presets)
+      when "doctor" then doctor
+      when "version" then return version
+      end
+      0
+    end
+
+    def render(args, options)
+      diagram = render_input(args, options)
+      output = options[:output]
+      format = output_format(options)
+      rendered = format == "ascii" ? diagram.to_ascii : diagram.to_svg
+      report_issues(diagram.issues, @input_name)
+      return 1 if options[:strict] && !diagram.issues.empty?
+
+      write_output(diagram, rendered, output, format)
+      0
+    end
+
+    def render_input(args, options)
+      preset = options[:preset]
+      expected = preset ? 0 : 1
+      raise OptionParser::InvalidArgument, "provide one INPUT or --preset NAME" unless args.length == expected
+
+      check_preset(preset) if preset
+      output_format(options)
+      @input_name = preset ? "preset:#{preset}" : args.first
+      overrides = Config.deep_merge(options[:overrides], options[:settings])
+      preset ? Bitgram.preset(preset, **overrides) : read_diagram(args.first, options, overrides)
+    end
+
+    def output_format(options)
+      output = options[:output]
+      format = options[:format] || FORMATS[File.extname(output.to_s).downcase] || "ascii"
+      if %w[png jpeg].include?(format) && [nil, "-"].include?(output)
+        raise OptionParser::InvalidArgument, "#{format} requires --output PATH"
+      end
+
+      format
+    end
+
+    def write_output(diagram, rendered, output, format)
+      if [nil, "-"].include?(output)
+        @stdout.write(rendered)
+      elsif %w[ascii svg].include?(format)
+        File.write(output, rendered)
+      else
+        diagram.save(output, format: format.to_sym)
+      end
+    end
+
+    def read_diagram(path, options, overrides = {})
+      if path == "-"
+        return Bitgram.load(@stdin.read(Loader::MAX_BYTES + 1), format: options[:input_format], **overrides)
+      end
+
+      Bitgram.load_file(path, format: options[:input_format], **overrides)
+    end
+
+    def validate(args, options)
+      raise OptionParser::MissingArgument, "INPUT" if args.empty?
+
+      codes = args.map do |path|
+        issues = if path == "-"
+                   read_diagram(path, options).issues
+                 else
+                   Bitgram.validate_file(path, format: options[:input_format])
+                 end
+        report_issues(issues, path)
+        issues.any? { |issue| issue.severity == :error || options[:strict] } ? 1 : 0
+      rescue ValidationError => e
+        report_issues(e.issues, path)
+        1
+      rescue ParseError => e
+        failure(e, 1)
+      rescue SystemCallError, IOError => e
+        failure(e, 4)
+      end
+      codes.max
+    end
+
+    def init(args)
+      raise OptionParser::InvalidArgument, "init accepts at most one PRESET" if args.length > 1
+
+      name = args.first || "udp"
+      check_preset(name)
+      @stdout.write(File.read(File.join(__dir__, "presets", "#{name}.yml"), encoding: "UTF-8"))
+      0
+    end
+
+    def check_preset(name)
+      return if Bitgram.presets.include?(name)
+
+      raise OptionParser::InvalidArgument, "unknown preset #{name.inspect}; choose #{Bitgram.presets.join(', ')}"
+    end
+
+    def report_issues(issues, filename)
+      issues.each do |issue|
+        location = [filename, issue.line].compact.join(":")
+        @stderr.puts("#{location}: #{issue.severity} #{issue.code} #{issue.path}: #{issue.message}")
+      end
+    end
+
+    def failure(error, code)
+      @stderr.puts(error.message)
+      @stderr.puts(error.backtrace) if @debug
+      code
+    end
+  end
+end
+
+require_relative "cli/options"
+require_relative "cli/doctor"

data/lib/bitgram/config.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # @api private
+  module Config
+    module_function
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each do |key, item|
+        key.freeze
+        deep_freeze(item)
+      end
+      when Array then value.each { |item| deep_freeze(item) }
+      end
+      value.freeze
+    end
+
+    DEFAULTS = {
+      "layout" => { "row_bits" => 32, "bit_order" => "msb0", "bit_numbers" => true,
+                    "offsets" => "none", "merge_rows" => true, "split_label" => "range",
+                    "split_suffix" => " [{from}:{to}]", "allow_partial_row" => false },
+      "ascii" => { "style" => "rfc", "indent" => 0, "variable_edge" => "dot", "max_label_lines" => 4,
+                   "ambiguous_width" => 1, "fit_order" => %w[single wrap short vertical footnote truncate],
+                   "footnote_marker" => "*{n}", "title" => "none" },
+      "svg" => { "theme" => "default", "bit_width" => 20, "row_height" => 36, "margin" => 16,
+                 "font_family" => "Helvetica, Arial, 'Noto Sans CJK JP', sans-serif", "font_size" => 13,
+                 "min_font_size" => 9, "char_width_ratio" => 0.6, "bit_number_style" => "full",
+                 "ticks" => true, "show_title" => true, "inline_styles" => false,
+                 "fit_order" => %w[single shrink wrap short vertical footnote truncate] },
+      "raster" => { "scale" => 2, "quality" => 90, "rasterizer" => "auto", "timeout" => 30 }
+    }.then { |defaults| deep_freeze(defaults) }
+
+    def deep_merge(base, extra)
+      base.merge(extra) do |_key, old, new|
+        old.is_a?(Hash) && new.is_a?(Hash) ? deep_merge(old, new) : new
+      end
+    end
+
+    def stringify(value, depth = 0)
+      raise ParseError, "input nesting exceeds 20 levels (or contains a cycle)" if depth > 20
+
+      case value
+      when Hash
+        value.to_h { |key, item| [key.to_s, stringify(item, depth + 1)] }
+      when Array then value.map { |item| stringify(item, depth + 1) }
+      when Symbol then value.to_s
+      when String then value.dup.force_encoding(Encoding::UTF_8)
+      when Numeric, true, false, nil then value
+      else raise ParseError, "unsupported input type: #{value.class}"
+      end
+    end
+
+    def slug(text)
+      text.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+    end
+  end
+end

data/lib/bitgram/diagram.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # A validated diagram with shared logical layout and format-specific rendering.
+  class Diagram
+    # @api private
+    def initialize(document, issues: [], source: nil)
+      @document = document
+      @issues = issues.dup
+      @source = source
+    end
+
+    # Logical bit coordinates for custom renderers and inspection.
+    # @return [Layout::Result]
+    def layout
+      @layout ||= Layout::Engine.new.call(@document)
+    end
+
+    # Validation warnings and findings collected during rendering.
+    # @return [Array<Issue>]
+    def issues
+      (@issues + layout.issues).uniq.freeze
+    end
+
+    # Render RFC or Unicode text. Keywords override the definition's ascii section.
+    # @return [String]
+    def to_ascii(**options)
+      render(:ascii, options).first
+    end
+
+    # Render SVG. Keywords override the definition's svg section.
+    # @return [String]
+    def to_svg(**options)
+      render(:svg, options).first
+    end
+
+    # Write a diagram, inferring format from the extension unless specified.
+    # @param path [String] output filename
+    # @param format [Symbol, nil] ascii, svg, png, or jpeg
+    # @return [String] output filename
+    def save(path, format: nil, **options)
+      format = (format || File.extname(path.to_s).delete_prefix(".")).to_s
+      format = { "txt" => "ascii", "jpg" => "jpeg" }.fetch(format, format)
+      case format
+      when "ascii" then File.write(path, to_ascii(**options))
+      when "svg" then File.write(path, to_svg(**options))
+      when "png", "jpeg" then save_raster(path, format.to_sym, options)
+      else raise ArgumentError, "unknown output format: #{format}"
+      end
+      path.to_s
+    end
+
+    private
+
+    def render(kind, options)
+      validate_options(kind, options)
+      require_relative "renderers/#{kind}"
+      klass = kind == :ascii ? Renderers::Ascii : Renderers::Svg
+      renderer = klass.new(layout, **options)
+      output = renderer.render
+      @issues |= renderer.issues
+      [output, renderer]
+    end
+
+    def validate_options(kind, options)
+      raw = Config.deep_merge(@source || { "version" => 1, "fields" => [] }, kind.to_s => Config.stringify(options))
+      errors = Validator.new.call(raw).select { |issue| issue.severity == :error }
+      raise ValidationError, errors unless errors.empty?
+    end
+
+    def save_raster(path, format, options)
+      svg_keys = Config::DEFAULTS["svg"].keys + ["id_prefix"]
+      svg_options, raster_options = options.partition { |key, _| svg_keys.include?(key.to_s) }.map(&:to_h)
+      validate_options(:raster, raster_options)
+      config = Config.deep_merge(@document.raster, Config.stringify(raster_options))
+      background = config.fetch("background", format == :jpeg ? "#ffffff" : "transparent")
+      raise RenderError, "JPEG cannot use a transparent background" if format == :jpeg && background == "transparent"
+
+      svg, renderer = render(:svg, svg_options.merge(inline_styles: true))
+      if renderer.width * renderer.height * (config["scale"]**2) > 50_000_000
+        raise RenderError, "output exceeds 50 million pixels; lower raster.scale"
+      end
+
+      require_relative "rasterizers/registry"
+      converter = Rasterizers::Registry.select(config["rasterizer"], format: format, timeout: config["timeout"])
+      converter.rasterize(svg, path: path.to_s, format: format, scale: config["scale"],
+                               background: background, quality: config["quality"])
+    end
+  end
+end

data/lib/bitgram/dsl.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # Builds a definition for the regular validation pipeline.
+  # @api private
+  class DSL
+    def initialize(title: nil)
+      @data = { "version" => 1, "title" => title, "layout" => {}, "fields" => [] }.compact
+    end
+
+    def row_bits(value)
+      @data["layout"]["row_bits"] = value
+    end
+
+    def bit_order(value)
+      @data["layout"]["bit_order"] = value.to_s
+    end
+
+    def field(name, **options)
+      @data["fields"] << { "name" => name, **options.transform_keys(&:to_s) }
+    end
+
+    def reserved(bits, name: "Reserved")
+      field(name, bits: bits, reserved: true)
+    end
+
+    def variable(name, **)
+      field(name, **, bits: "variable")
+    end
+
+    def to_h
+      @data
+    end
+  end
+end

data/lib/bitgram/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # Base error for definition and rendering failures.
+  class Error < StandardError; end
+  # Malformed or unsafe serialized input.
+  class ParseError < Error; end
+
+  # Invalid definition; all validation findings are available in #issues.
+  class ValidationError < Error
+    attr_reader :issues
+
+    def initialize(issues)
+      @issues = issues.freeze
+      super(issues.join("\n"))
+    end
+  end
+
+  # The definition cannot be laid out.
+  class LayoutError < Error; end
+  # The requested output cannot be rendered.
+  class RenderError < Error; end
+  # Raster conversion failed.
+  class RasterizeError < Error; end
+  # No installed converter supports the requested format.
+  class RasterizerNotFound < RasterizeError; end
+  # An external converter exceeded its deadline.
+  class RasterizerTimeout < RasterizeError; end
+end

data/lib/bitgram/issue.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # A validation or rendering finding, including a JSON path and optional YAML line.
+  Issue = Data.define(:severity, :code, :path, :line, :message) do
+    # Format the finding for logs and command-line diagnostics.
+    def to_s
+      [line && "line #{line}:", severity, code, "#{path}:", message].compact.join(" ")
+    end
+  end
+end