graphomaton 0.1.1 → 1.1.0

data/docs/architecture.md

@@ -0,0 +1,30 @@
+# Architecture
+
+Graphomaton processes data through explicit boundaries:
+
+```text
+JSON / YAML / Ruby builder
+          ↓
+immutable State, Transition, and Label records
+          ↓
+validation profiles and revision-cached graph analysis
+          ↓
+exporter capability and semantic-loss checks
+          ↓
+layout → SVG scene, or syntax-specific text exporter
+          ↓
+optional bounded native conversion to PNG, PDF, or WebP
+```
+
+The public builder mutates the graph only through validated methods and increments
+`revision` after every effective change. Analysis indexes and layouts are rebuilt
+only when the revision changes. Exporters consume immutable record snapshots; the
+legacy `states` and `transitions` readers expose frozen compatibility hashes.
+
+SVG is the native visual format. Raster and PDF exporters keep SVG logical
+coordinates stable and adjust only output pixel dimensions. DOT, Mermaid, and
+PlantUML allocate internal identifiers independently from labels. Every exporter
+declares its capabilities so unsupported semantics can be diagnosed or rejected.
+
+External processes run in their own process group with a timeout and stdout/stderr
+limits. File output uses a same-directory temporary file and atomic rename.

data/docs/cli.md

@@ -0,0 +1,27 @@
+# Command-line reference
+
+`graphomaton render INPUT OUTPUT` is the explicit form of the compatible
+`graphomaton INPUT OUTPUT` command. Use `-` for stdin or stdout; stdout requires
+`--format`. Rendering validates references by default.
+
+`graphomaton validate INPUT --diagnostics json` validates references, hierarchy,
+FSM warnings, and DFA constraints without writing a diagram. Add
+`--fail-on-warning` for CI. `graphomaton list` reports formats, layouts, themes,
+and converters; `doctor` reports the Ruby version plus discovered native renderer
+paths and bounded version probes.
+
+Configuration resolution is defaults, `.graphomaton.yml`, environment, then CLI.
+`GRAPHOMATON_CONFIG` selects another config. Supported scalar environment values
+are `GRAPHOMATON_FORMAT`, `GRAPHOMATON_THEME`, `GRAPHOMATON_LAYOUT`,
+`GRAPHOMATON_WIDTH`, and `GRAPHOMATON_HEIGHT`.
+
+Exit statuses are stable: 0 success, 2 usage, 3 input, 4 validation, 5 layout, 6
+export/conversion, and 7 security policy. Normal failures omit backtraces; pass
+`--debug` while investigating.
+
+Input budgets can be lowered with `--max-input-bytes`, `--max-states`,
+`--max-transitions`, `--max-metadata-depth`, `--max-label-length`, and
+`--max-group-depth`.
+
+Generate integration files with `graphomaton completion bash|zsh|fish` and
+`graphomaton man`.

data/docs/custom-exporters.md

@@ -0,0 +1,36 @@
+# Custom exporters
+
+Applications can register an exporter class with a canonical format name, aliases,
+filename extensions, binary mode, and the semantics it preserves:
+
+```ruby
+class TextExporter
+  def initialize(graph)
+    @graph = graph
+  end
+
+  def export(width, height, prefix: 'graph')
+    "#{prefix}: #{@graph.state_records.size} states on #{width}x#{height}\n"
+  end
+end
+
+Graphomaton.register_exporter(
+  :text_graph,
+  aliases: %i[tg],
+  extensions: %w[textgraph tg],
+  capabilities: %i[group],
+  exporter: TextExporter
+)
+
+graph.render(format: :tg, prefix: 'machine')
+```
+
+An exporter class must accept the graph in `initialize` and implement
+`export(width, height, **options)`. A loader block can be used instead of the
+`exporter:` argument to defer loading optional dependencies. Registration rejects
+names, aliases, and extensions that another exporter already owns.
+
+Capability omissions are reported by `semantic_diagnostics` and rejected when
+`strict_semantics: true` is used. Set `binary: true` when output must be written in
+binary mode. A temporary registration can be removed with
+`Graphomaton::EXPORTERS.unregister(:text_graph)`.

data/docs/exporters.md

@@ -0,0 +1,17 @@
+# Exporter capabilities
+
+| Feature | SVG/PNG/PDF/WebP | DOT | Mermaid | PlantUML |
+| --- | --- | --- | --- | --- |
+| styles and line styles | yes | partial | partial | partial |
+| URL and tooltip | yes | yes | no | no |
+| visual groups | yes | yes | partial | partial |
+| hierarchy and pseudostates | display | partial | yes | yes |
+| edge bundles | yes | no | no | no |
+
+Use `semantic_diagnostics(format)` to inspect loss, `strict_semantics: true` to
+reject it, and `render_result` to obtain output, diagnostics, bounds, and resolved
+SVG layout together.
+
+`group` is a visual cluster. `parent` is a semantic hierarchy relationship. They
+cannot be assigned to the same state. Graph analysis follows transitions and does
+not infer statechart execution semantics from visual groups.

data/docs/input-schema.md

@@ -0,0 +1,26 @@
+# Input schema version 1
+
+The top-level mapping accepts `version`, `states`, `transitions`, `initial` (or
+`initial_state`), and `final` (or `final_states`). Unknown keys are errors by
+default. `version` is optional for compatibility and, when present, must be `1`.
+
+States may be an array or a mapping keyed by state ID. A state mapping accepts
+`id`, `name`, `x`, `y`, `label`, `style`, `metadata`, `shape`, `kind`, `initial`,
+`final`, and `accepting`. `kind` is `normal`, `choice`, `fork`, or `join`. State IDs
+must be unique. `initial` is singular. `metadata.parent`
+must name an existing state and may not form a cycle or coexist with a visual
+`group`.
+
+Transitions are an array. Each item is either a mapping with `from`, `to`, and
+`label`, or a three-element tuple. Mapping options are `style`, `metadata`, and
+`line_style`. Reference validation is deferred in the Ruby library and enabled by
+default in the CLI.
+
+State and transition `style` and `metadata` values must be mappings. State labels
+are scalar display text. Transition labels may be scalar text, a symbol array, or
+a structured label with an explicit `type`/`kind`; malformed collections are
+rejected instead of being stringified or ignored.
+
+YAML aliases are disabled. Parsing limits input bytes, state and transition
+counts, label bytes, metadata depth, and hierarchy depth. Callers handling
+untrusted data should lower the defaults for their service budget.

data/docs/migration-1.1.md

@@ -0,0 +1,19 @@
+# Migrating to 1.1
+
+Builder methods now return the graph, enabling chaining. Duplicate `add_state`
+calls raise; use `upsert_state` for replacement. Public `states` and `transitions`
+are frozen compatibility snapshots, so mutations must use update/remove methods.
+An upsert that omits coordinates preserves an existing manual position; pass both
+`x` and `y` as `nil` to clear it explicitly.
+
+Input schema keys are strict by default and YAML aliases are disabled. Pass
+`strict_schema: false` only while migrating legacy documents, and enable aliases
+only for trusted YAML.
+
+The CLI validates references by default, rejects options unsupported by the
+selected format, and assigns distinct exit statuses. Use `--no-validate` only for
+intentional partial diagrams.
+
+Semantic loss is reported for exporters that cannot preserve requested metadata.
+Use `strict_semantics: true` or `--strict-semantics` when silent degradation is not
+acceptable.

data/docs/performance.md

@@ -0,0 +1,19 @@
+# Performance and limits
+
+Input defaults are 10 MiB, 10,000 states, 100,000 transitions, metadata depth 64,
+and hierarchy depth 64. Canvas area and force iteration counts are bounded. Set
+lower limits at untrusted service boundaries.
+
+Graph analysis uses revision-cached incoming, outgoing, and transition-pair
+indexes. SCC traversal is iterative. Repeated layouts with identical options are
+cached until the graph changes. Force layout switches from exact pair repulsion
+to a Barnes-Hut quadtree for large graphs. SVG label collision uses a bounded
+uniform-grid index; unusually large boxes fall back to a bounded overflow list.
+
+Run `ruby -Ilib benchmark/render_svg.rb [COUNTS...]` to measure 100, 1,000, and
+10,000 transition renders on the local runtime. This benchmark deliberately does
+not set a pass/fail time because Ruby, CPU, and renderer configurations vary.
+
+REXML builds the complete SVG DOM in memory. Very large outputs therefore need
+memory proportional to generated SVG. Native conversions additionally enforce a
+timeout and output byte limit.

data/docs/releasing.md

@@ -0,0 +1,19 @@
+# Release policy
+
+Graphomaton follows semantic versioning. Patch releases contain compatible fixes,
+minor releases contain compatible features and announced deprecations, and major
+releases may remove deprecated behavior. Security fixes target the latest release
+as described in `SECURITY.md`.
+
+To release:
+
+1. Move completed entries from Unreleased to a dated version section.
+2. Set `Graphomaton::VERSION` to the same version and run `bundle exec rake`.
+3. Build and locally install the gem and smoke-test `graphomaton --version`.
+4. Push the signed or annotated `vVERSION` tag.
+
+The tag workflow verifies the tag/version match, reruns tests and RBS validation,
+builds and installs the package, then uses RubyGems trusted publishing with a
+short-lived OIDC token. The RubyGems publisher must be configured for
+`.github/workflows/release.yml` and the protected `release` environment. No
+long-lived RubyGems API key is stored in the repository.

data/exe/graphomaton

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib_path = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib_path) if File.directory?(lib_path)
+
+require 'graphomaton/cli'
+
+exit Graphomaton::CLI.new.run(ARGV)

data/lib/graphomaton/atomic_file.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+class Graphomaton
+  class AtomicFile
+    def self.write(filename, content, binary: false)
+      destination = File.expand_path(filename)
+      directory = File.dirname(destination)
+      basename = File.basename(destination)
+      existing_mode = File.stat(destination).mode & 0o7777 if File.exist?(destination)
+
+      Tempfile.create([".#{basename}", '.tmp'], directory, binmode: binary) do |temporary|
+        temporary.binmode if binary
+        temporary.chmod(existing_mode) if existing_mode
+        temporary.write(content)
+        temporary.flush
+        temporary.fsync
+        temporary.close
+        File.rename(temporary.path, destination)
+      end
+
+      content.bytesize
+    end
+  end
+end

data/lib/graphomaton/cli/config.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+class Graphomaton
+  class CLI
+    class Config
+      DEFAULT_PATH = '.graphomaton.yml'
+      MAX_BYTES = 1024 * 1024
+      FORMAT_SECTIONS = %i[svg png pdf webp html mermaid dot plantuml].freeze
+      ENUM_KEYS = %i[
+        format input_format theme layout direction fit converter initial_position final_position
+        state_shape edge_style arrow_shape state_effect unreachable_zone loop_position diagnostics
+      ].freeze
+      OPTION_KEYS = %i[
+        input input_format output format validate no_clobber width height scale converter timeout
+        max_output_bytes max_input_bytes max_states max_transitions max_metadata_depth max_label_length
+        max_group_depth theme theme_file layout_warnings
+        layout direction fit padding node_spacing rank_spacing force_iterations layout_seed
+        graphviz_command auto_density_spacing initial_position final_position responsive state_radius
+        auto_state_radius min_state_radius max_state_radius state_stroke_width transition_stroke_width
+        state_shape edge_style arrow_shape arrow_size state_effect font_family state_font_weight
+        transition_font_weight preserve_manual_positions auto_size xml_declaration pretty minify
+        css_variables embed_styles svg_id wrap max_transition_label_width state_wrap
+        max_state_label_width label_tooltips html_tooltips sort_labels rotate_labels label_padding
+        label_radius label_border label_background initial_arrow_length initial_arrow_label
+        final_arrow_length final_arrow_label show_final_arrows scc_groups fold_groups
+        highlight_unreachable unreachable_zone highlight_dead_states highlight_initial_state
+        highlight_final_states loop_position merge_parallel_transitions title description cdn offline
+        inline_mermaid lang show_source pan_zoom mathjax mathjax_cdn notes class_defs rank_constraints
+        inline_mathjax self_contained nonce csp mermaid_sha256 mathjax_sha256
+        fail_on_warning diagnostics strict_semantics
+      ].freeze
+      LABEL_KEYS = {
+        wrap: :wrap,
+        max_width: :max_transition_label_width,
+        max_transition_width: :max_transition_label_width,
+        state_wrap: :state_wrap,
+        max_state_width: :max_state_label_width,
+        tooltips: :label_tooltips,
+        html_tooltips: :html_tooltips,
+        rotate: :rotate_labels,
+        padding: :label_padding,
+        radius: :label_radius,
+        border: :label_border,
+        background: :label_background
+      }.freeze
+
+      def self.load(path, format: nil, required: false)
+        return {} if path.nil?
+        return {} unless File.exist?(path) || required
+
+        payload = File.open(path, 'rb') { |input| input.read(MAX_BYTES + 1) }
+        raise ArgumentError, "Config exceeds #{MAX_BYTES} bytes" if payload.bytesize > MAX_BYTES
+
+        parsed = YAML.safe_load(payload, permitted_classes: [Symbol], aliases: false) || {}
+        raise ArgumentError, 'Config root must be a mapping' unless parsed.is_a?(Hash)
+
+        normalized = symbolize_hash(parsed)
+        unknown_sections = normalized.keys - OPTION_KEYS - [:render] - FORMAT_SECTIONS
+        raise ArgumentError, "Unknown config keys: #{unknown_sections.join(', ')}" unless unknown_sections.empty?
+
+        common = normalized.reject { |key, _value| key == :render || FORMAT_SECTIONS.include?(key) }
+        render = mapping(normalized[:render], 'render')
+        format_options = format ? mapping(normalized[format.to_sym], format) : {}
+        normalize_options(common.merge(render).merge(format_options))
+      rescue Psych::Exception, SystemCallError => e
+        raise ArgumentError, "Config error: #{e.message}"
+      end
+
+      def self.mapping(value, name)
+        return {} if value.nil?
+        raise ArgumentError, "Config #{name} section must be a mapping" unless value.is_a?(Hash)
+
+        value
+      end
+      private_class_method :mapping
+
+      def self.normalize_options(input)
+        labels = mapping(input.delete(:labels), 'labels')
+        unknown_labels = labels.keys - LABEL_KEYS.keys
+        raise ArgumentError, "Unknown config label keys: #{unknown_labels.join(', ')}" unless unknown_labels.empty?
+
+        options = input.merge(labels.to_h { |key, value| [LABEL_KEYS.fetch(key), value] })
+        unknown = options.keys - OPTION_KEYS
+        raise ArgumentError, "Unknown config option keys: #{unknown.join(', ')}" unless unknown.empty?
+
+        options.to_h do |key, value|
+          normalized = ENUM_KEYS.include?(key) && value.is_a?(String) ? value.to_sym : value
+          [key, normalized]
+        end
+      end
+      private_class_method :normalize_options
+
+      def self.symbolize_hash(value)
+        value.to_h do |key, item|
+          normalized = item.is_a?(Hash) ? symbolize_hash(item) : item
+          [key.to_s.to_sym, normalized]
+        end
+      end
+      private_class_method :symbolize_hash
+    end
+  end
+end