bitgram 0.1.0

data/lib/bitgram/text/fitter.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "measurer"
+
+module Bitgram
+  # @api private
+  module Text
+    # @api private
+    FitResult = Data.define(:lines, :font_size, :strategy, :footnote)
+
+    # @api private
+    class Fitter
+      attr_reader :footnotes, :issues
+
+      def initialize(measurer:, font_size: nil, min_font_size: nil, footnote_marker: "*{n}")
+        @measurer = measurer
+        @font_size = font_size
+        @min_font_size = min_font_size
+        @footnote_marker = footnote_marker.gsub(/\s+/, " ")
+        @footnotes = []
+        @issues = []
+      end
+
+      def fit(text:, inner_width:, order:, **options)
+        text = text.gsub(/\s+/, " ").strip
+        options[:short] = options[:short].gsub(/\s+/, " ").strip if options[:short]
+        order.each do |strategy|
+          result = attempt(strategy.to_sym, text, inner_width, options)
+          return result if result
+        end
+        truncate(text, inner_width, options.fetch(:path, "$.fields"))
+      end
+
+      private
+
+      def attempt(strategy, text, width, options)
+        max_lines = options.fetch(:max_lines, 4)
+        short = options[:short]
+        case strategy
+        when :single then result([text], :single) if fits?(text, width)
+        when :short then result([short], :short) if short && fits?(short, width)
+        when :shrink then shrink(text, width)
+        when :wrap, :vertical then multiline(text, width, max_lines, strategy)
+        when :footnote then footnote(options[:description] || text, width, max_lines)
+        when :truncate then truncate(text, width, options.fetch(:path, "$.fields"))
+        end
+      end
+
+      def multiline(text, width, max_lines, strategy)
+        lines = strategy == :wrap ? wrap(text, width) : text.scan(/\X/).grep_v(/\s/)
+        return unless lines && lines.size <= max_lines && lines.all? { |line| fits?(line, width) }
+
+        result(lines, strategy)
+      end
+
+      def fits?(text, width)
+        @measurer.width(text) <= width
+      end
+
+      def result(lines, strategy, size = @font_size, footnote = nil)
+        FitResult.new(lines.freeze, size, strategy, footnote)
+      end
+
+      def shrink(text, width)
+        return unless @font_size && @min_font_size
+
+        size = @font_size - 0.5
+        while size >= @min_font_size
+          return result([text], :shrink, size) if @measurer.width(text, size: size) <= width
+
+          size -= 0.5
+        end
+        nil
+      end
+
+      def wrap(text, width)
+        tokens = text.scan(/[\p{Han}\p{Hiragana}\p{Katakana}]|[^\s\p{Han}\p{Hiragana}\p{Katakana}]+|\s+/)
+        tokens = join_punctuation(tokens)
+        lines = []
+        line = ""
+        tokens.each do |token|
+          next if line.empty? && token.match?(/\A\s+\z/)
+
+          if fits?(line + token, width)
+            line += token
+          else
+            lines << line.rstrip unless line.empty?
+            line = token.lstrip
+            return nil unless fits?(line, width)
+          end
+        end
+        lines << line.rstrip unless line.empty?
+        lines.empty? ? [""] : lines
+      end
+
+      def join_punctuation(tokens)
+        tokens.each_with_object([]) do |token, joined|
+          if token.match?(/\A[、。,.)」]/) && !joined.empty?
+            joined[-1] += token
+          else
+            joined << token
+          end
+        end
+      end
+
+      def footnote(body, width, max_lines)
+        marker = @footnote_marker.gsub("{n}", (@footnotes.size + 1).to_s)
+        lines = fits?(marker, width) ? [marker] : marker.scan(/\X/)
+        return unless lines.size <= max_lines && lines.all? { |line| fits?(line, width) }
+
+        @footnotes << "#{marker}: #{body}"
+        result(lines, :footnote, @font_size, body)
+      end
+
+      def truncate(text, width, path)
+        suffix = fits?("…", width) ? "…" : ""
+        remaining = width - @measurer.width(suffix)
+        prefix = +""
+        text.scan(/\X/) do |char|
+          char_width = @measurer.width(char)
+          # SVG widths can accumulate subpixel floating-point roundoff.
+          break if char_width > remaining + 1e-9
+
+          prefix << char
+          remaining -= char_width
+        end
+        @issues << Issue.new(:warning, "V-09", path, nil, "label was truncated to fit its cell")
+        result([prefix + suffix], :truncate)
+      end
+    end
+  end
+end

data/lib/bitgram/text/measurer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "unicode/display_width"
+
+module Bitgram
+  module Text
+    # @api private
+    class AsciiMeasurer
+      def initialize(ambiguous: 1)
+        @display_width = Unicode::DisplayWidth.new(ambiguous: ambiguous, emoji: :all)
+      end
+
+      def width(string)
+        @display_width.of(string)
+      end
+    end
+
+    # @api private
+    class SvgMeasurer < AsciiMeasurer
+      def initialize(font_size:, ratio:, ambiguous: 1)
+        super(ambiguous: ambiguous)
+        @font_size = font_size
+        @ratio = ratio
+      end
+
+      def width(string, size: @font_size)
+        super(string) * size * @ratio
+      end
+    end
+  end
+end

data/lib/bitgram/themes/dark.yml

@@ -0,0 +1,11 @@
+background: "#0d1117"
+stroke: "#c9d1d9"
+text: "#e6edf3"
+header_text: "#8b949e"
+cell_fill: "#161b22"
+reserved_fill: "#30363d"
+hatch: "#6e7681"
+palette: []
+classes:
+  header:
+    fill: "#0c2d6b"

data/lib/bitgram/themes/default.yml

@@ -0,0 +1,11 @@
+background: "#ffffff"
+stroke: "#1f2328"
+text: "#1f2328"
+header_text: "#57606a"
+cell_fill: "#ffffff"
+reserved_fill: "#eaeef2"
+hatch: "#8c959f"
+palette: []
+classes:
+  header:
+    fill: "#ddf4ff"

data/lib/bitgram/themes/mono.yml

@@ -0,0 +1,9 @@
+background: "#ffffff"
+stroke: "#000000"
+text: "#000000"
+header_text: "#000000"
+cell_fill: "#ffffff"
+reserved_fill: "#eeeeee"
+hatch: "#777777"
+palette: []
+classes: {}

data/lib/bitgram/util/command.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module Bitgram
+  # @api private
+  module Util
+    # @api private
+    module Command
+      module_function
+
+      def which(name)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR)
+           .map { |directory| File.join(directory, name) }
+           .find { |path| File.executable?(path) && !File.directory?(path) }
+      end
+
+      def run(command, stdin_data:, timeout:)
+        Open3.popen3(*command, pgroup: true) do |stdin, stdout, stderr, process|
+          threads = [Thread.new { write_input(stdin, stdin_data) },
+                     Thread.new { stdout.read }, Thread.new { stderr.read }]
+          begin
+            Timeout.timeout(timeout, RasterizerTimeout, "#{command.first} timed out after #{timeout}s") do
+              threads.each(&:join)
+              raise RasterizeError, "#{command.first} failed: #{threads[2].value.strip}" unless process.value.success?
+
+              threads[1].value
+            end
+          ensure
+            # Kill the process group as delegates can otherwise retain open pipes.
+            begin
+              Process.kill(:KILL, -process.pid)
+            rescue Errno::ESRCH
+              nil
+            end
+            threads.each { |thread| thread.kill.join }
+          end
+        end
+      rescue Errno::ENOENT => e
+        raise RasterizeError, e.message
+      end
+
+      def write_input(stdin, data)
+        stdin.write(data)
+      rescue Errno::EPIPE, IOError
+        nil # The process exit status reports early input rejection.
+      ensure
+        stdin.close
+      end
+    end
+  end
+end

data/lib/bitgram/validator.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "did_you_mean"
+
+module Bitgram
+  # @api private
+  # Uses the shipped schema for structural checks, then checks relationships between fields.
+  class Validator
+    SCHEMA = Config.deep_freeze(JSON.parse(File.read(File.expand_path("../../schema/bitgram.schema.json", __dir__))))
+
+    def initialize(line_map: {})
+      @line_map = line_map
+    end
+
+    def call(data)
+      @issues = []
+      check(data, SCHEMA, "$")
+      check_fields(data) if data.is_a?(Hash) && data["fields"].is_a?(Array)
+      @issues
+    end
+
+    private
+
+    def add(code, path, message, severity = :error)
+      parent = path
+      until @line_map.key?(parent) || parent == "$" || parent.empty?
+        ancestor = parent.sub(/(?:\.[^.\[]+|\[\d+\])\z/, "")
+        parent = ancestor == parent ? "$" : ancestor
+      end
+      @issues << Issue.new(severity, code, path, @line_map[parent], message)
+    end
+
+    def check(value, rule, path)
+      rule = SCHEMA.fetch("$defs").fetch(rule["$ref"].split("/").last) if rule["$ref"]
+      if rule["type"] && Array(rule["type"]).none? { |type| type_match?(value, type) }
+        add("V-03", path, "must be #{Array(rule['type']).join(' or ')}")
+        return
+      end
+      check_scalar(value, rule, path)
+      check_object(value, rule, path) if value.is_a?(Hash)
+      check_array(value, rule, path) if value.is_a?(Array)
+      check_choice(value, rule, path) if rule["oneOf"]
+    end
+
+    def check_choice(value, rule, path)
+      if path.match?(/\A\$\.fields\[\d+\]\z/)
+        add("V-04", path, "specify exactly one of bits and bytes") unless (value.keys & %w[bits bytes]).size == 1
+      elsif rule["oneOf"].count { |branch| matches?(value, branch) } != 1
+        add("V-03", path, "value does not match an allowed type or range")
+      end
+    end
+
+    def type_match?(value, type)
+      case type
+      when "object" then value.is_a?(Hash)
+      when "array" then value.is_a?(Array)
+      when "string" then value.is_a?(String)
+      when "integer" then value.is_a?(Integer)
+      when "number" then value.is_a?(Numeric) && value.real? && value.finite?
+      when "boolean" then [true, false].include?(value)
+      end
+    end
+
+    def matches?(value, rule)
+      previous = @issues
+      @issues = []
+      check(value, rule, "$")
+      @issues.empty?
+    ensure
+      @issues = previous
+    end
+
+    def check_scalar(value, rule, path)
+      if rule.key?("const") && value != rule["const"]
+        add(path == "$.version" ? "V-01" : "V-03", path, "must equal #{rule['const'].inspect}")
+      end
+      add("V-03", path, "must be one of #{rule['enum'].join(', ')}") if rule["enum"] && !rule["enum"].include?(value)
+      check_number(value, rule, path) if value.is_a?(Numeric)
+      check_string(value, rule, path) if value.is_a?(String)
+    end
+
+    def check_number(value, rule, path)
+      unless value.real? && value.finite?
+        add("V-03", path, "must be finite")
+        return
+      end
+      add("V-03", path, "must be at least #{rule['minimum']}") if rule["minimum"] && value < rule["minimum"]
+      add("V-07", path, "must be at most #{rule['maximum']}") if rule["maximum"] && value > rule["maximum"]
+    end
+
+    def check_string(value, rule, path)
+      unless value.valid_encoding? && !value.match?(/[\x00-\x08\x0b\x0c\x0e-\x1f\uFFFE\uFFFF]/)
+        add("V-03", path,
+            "must be valid UTF-8 text without control characters")
+        return
+      end
+      if rule["minLength"] && value.length < rule["minLength"]
+        add("V-03", path,
+            "must have at least #{rule['minLength']} characters")
+      end
+      if rule["maxLength"] && value.length > rule["maxLength"]
+        add("V-07", path,
+            "must have at most #{rule['maxLength']} characters")
+      end
+      pattern = rule["pattern"]
+      return unless pattern && !Regexp.new("\\A#{pattern.delete_prefix('^').delete_suffix('$')}\\z").match?(value)
+
+      add("V-03", path,
+          "invalid format")
+    end
+
+    def check_object(value, rule, path)
+      properties = rule.fetch("properties", {})
+      if rule["additionalProperties"] == false
+        (value.keys - properties.keys).each do |key|
+          hint = DidYouMean::SpellChecker.new(dictionary: properties.keys).correct(key.to_s).first
+          add("V-02", "#{path}.#{key}", "unknown key #{key.inspect}#{" (did you mean #{hint.inspect}?)" if hint}")
+        end
+      end
+      Array(rule["required"]).each { |key| add("V-03", "#{path}.#{key}", "is required") unless value.key?(key) }
+      properties.each { |key, child| check(value[key], child, "#{path}.#{key}") if value.key?(key) }
+    end
+
+    def check_array(value, rule, path)
+      add("V-03", path, "must not be empty") if rule["minItems"] && value.size < rule["minItems"]
+      if rule["maxItems"] && value.size > rule["maxItems"]
+        add("V-07", path,
+            "too many items (maximum #{rule['maxItems']})")
+        return
+      end
+      add("V-03", path, "items must be unique") if rule["uniqueItems"] && value.uniq.size != value.size
+      value.each_with_index { |item, i| check(item, rule["items"], "#{path}[#{i}]") } if rule["items"]
+    end
+
+    def check_fields(data)
+      return if data["fields"].size > 10_000
+
+      fields = data["fields"].grep(Hash)
+      seen = {}
+      fields.each_with_index do |field, i|
+        id = field["id"]
+        add("V-05", "$.fields[#{i}].id", "duplicate id #{id.inspect}") if id && seen[id]
+        seen[id] = true if id
+      end
+      return if @issues.any? { |issue| issue.severity == :error }
+
+      check_positions(fields, data.fetch("layout", {}))
+    end
+
+    def check_positions(fields, layout)
+      width = layout.fetch("row_bits", 32)
+      pos = 0
+      fields.each_with_index do |field, i|
+        variable = field["bits"] == "variable"
+        bits = variable ? field.fetch("display_bits", width) : field.fetch("bits") { field["bytes"] * 8 }
+        check_variable(field, i, pos, width, bits) if variable
+        pos += bits
+      end
+      add("V-07", "$.fields", "diagram exceeds 4096 logical rows") if (pos.to_f / width).ceil > 4096
+      return unless pos % width != 0 && !layout["allow_partial_row"]
+
+      add("V-08", "$.fields", "last row is #{pos % width}/#{width} bits; set layout.allow_partial_row to silence",
+          :warning)
+    end
+
+    def check_variable(field, index, position, width, bits)
+      if !field.key?("display_bits") && position % width != 0
+        add("V-06", "$.fields[#{index}]", "full-width variable field must start at a row boundary")
+      elsif bits > width - (position % width)
+        add("V-10", "$.fields[#{index}].display_bits", "variable field extends past the row boundary", :warning)
+      end
+    end
+  end
+end

data/lib/bitgram/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Bitgram
+  # Current gem version; the definition format has its own version field.
+  VERSION = "0.1.0"
+end

data/lib/bitgram.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "bitgram/version"
+require_relative "bitgram/errors"
+require_relative "bitgram/issue"
+require_relative "bitgram/config"
+require_relative "bitgram/loader"
+require_relative "bitgram/validator"
+require_relative "bitgram/model/field"
+require_relative "bitgram/model/document"
+require_relative "bitgram/normalizer"
+require_relative "bitgram/layout/engine"
+require_relative "bitgram/diagram"
+
+# Declarative packet and bit-field diagrams with shared layout across output formats.
+module Bitgram
+  autoload :CLI, "bitgram/cli"
+  # Load a YAML/JSON string or Ruby Hash and apply nested configuration overrides.
+  # @return [Diagram]
+  def self.load(input = nil, format: nil, **overrides)
+    if input.nil?
+      input = overrides
+      overrides = {}
+    end
+    source = if input.is_a?(Hash)
+               Loader::Source.new(Config.stringify(input), {},
+                                  nil)
+             else
+               Loader.new.load_string(input, format: format)
+             end
+    build(source, overrides)
+  end
+
+  # Load a definition from disk.
+  # @return [Diagram]
+  def self.load_file(path, format: nil, **overrides)
+    build(Loader.new.load_file(path, format: format), overrides)
+  end
+
+  # Validate a file without raising definition or parse exceptions.
+  # @return [Array<Issue>]
+  def self.validate_file(path, format: nil, **overrides)
+    source = Loader.new.load_file(path, format: format)
+    data = source.data.is_a?(Hash) ? Config.deep_merge(source.data, Config.stringify(overrides)) : source.data
+    Validator.new(line_map: source.line_map).call(data)
+  rescue ParseError => e
+    [Issue.new(:error, "PARSE", "$", nil, e.message)]
+  end
+
+  # Names of bundled protocol definitions.
+  # @return [Array<String>]
+  def self.presets
+    Dir[File.join(__dir__, "bitgram/presets/*.yml")].map { |path| File.basename(path, ".yml") }.sort
+  end
+
+  # Load a bundled protocol definition.
+  # @return [Diagram]
+  def self.preset(name, **overrides)
+    raise ArgumentError, "unknown preset: #{name}; choose #{presets.join(', ')}" unless presets.include?(name.to_s)
+
+    load_file(File.join(__dir__, "bitgram/presets/#{name}.yml"), **overrides)
+  end
+
+  # Build a definition with the Ruby DSL, using the same validation as file inputs.
+  # @return [Diagram]
+  def self.define(**, &)
+    require_relative "bitgram/dsl"
+    dsl = DSL.new(**)
+    dsl.instance_eval(&)
+    load(dsl.to_h)
+  end
+
+  # @api private
+  def self.build(source, overrides)
+    data = source.data.is_a?(Hash) ? Config.deep_merge(source.data, Config.stringify(overrides)) : source.data
+    issues = Validator.new(line_map: source.line_map).call(data)
+    raise ValidationError, issues if issues.any? { |issue| issue.severity == :error }
+
+    Diagram.new(Normalizer.new.call(data), issues: issues, source: Config.deep_freeze(Config.stringify(data)))
+  end
+  private_class_method :build
+end