elkrb 1.0.0 → 2.0.0

data/lib/elkrb.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "logger"
+
 require_relative "elkrb/version"
 require_relative "elkrb/errors"
 
@@ -10,7 +12,9 @@ require_relative "elkrb/geometry/rectangle"
 require_relative "elkrb/geometry/vector"
 
 # Graph models
-require_relative "elkrb/graph/layout_options"
+require_relative "elkrb/graph/deep_stringify_keys"
+require_relative "elkrb/graph/normalize_option_keys"
+require_relative "elkrb/graph/read_only_mapping"
 require_relative "elkrb/graph/label"
 require_relative "elkrb/graph/port"
 require_relative "elkrb/graph/node_constraints"
@@ -20,11 +24,17 @@ require_relative "elkrb/graph/graph"
 
 # Serializers
 require_relative "elkrb/serializers/dot_serializer"
+require_relative "elkrb/serializers/elkt_serializer"
+
+# Parsers
+require_relative "elkrb/parsers/elkt_parser"
 
 # Options parsers
 require_relative "elkrb/options/elk_padding"
 require_relative "elkrb/options/k_vector"
 require_relative "elkrb/options/k_vector_chain"
+require_relative "elkrb/options/registry"
+require_relative "elkrb/options/resolver"
 
 # Layout constraints
 require_relative "elkrb/layout/constraints/base_constraint"
@@ -57,7 +67,7 @@ require_relative "elkrb/layout/algorithms/vertiflex"
 # ElkRb - Pure Ruby implementation of the Eclipse Layout Kernel
 #
 # ElkRb provides automatic graph layout algorithms for node-link diagrams.
-# It implements 12 layout algorithms from the Eclipse Layout Kernel (ELK),
+# It implements the layout algorithms from the Eclipse Layout Kernel (ELK),
 # supporting hierarchical graphs, port-based connections, and automatic
 # label placement.
 #
@@ -77,7 +87,7 @@ require_relative "elkrb/layout/algorithms/vertiflex"
 #   }
 #
 #   result = Elkrb.layout(graph)
-#   puts result[:children][0][:x]  # Node positions computed
+#   puts result.children[0].x  # Node positions computed
 #
 # @example Using model classes
 #   graph = Elkrb::Graph::Graph.new(id: "root")
@@ -94,6 +104,19 @@ require_relative "elkrb/layout/algorithms/vertiflex"
 # @see https://www.eclipse.org/elk/ Eclipse Layout Kernel
 # @see https://github.com/kieler/elkjs elkjs - JavaScript port
 module Elkrb
+  # The logger every elkrb warning goes through. Defaults to WARN on $stderr;
+  # assign your own to redirect or silence it.
+  #
+  # @return [Logger]
+  def self.logger
+    @logger ||= Logger.new($stderr, level: Logger::WARN)
+  end
+
+  # @param logger [Logger] replaces the default logger
+  def self.logger=(logger)
+    @logger = logger
+  end
+
   # Register basic layout algorithms
   Layout::AlgorithmRegistry.register(
     "random",
@@ -237,7 +260,9 @@ module Elkrb
     Layout::Algorithms::Libavoid,
     {
       name: "Libavoid",
-      description: "Orthogonal connector routing with obstacle avoidance",
+      description: "Orthogonal connector routing with bounded A* obstacle " \
+                   "avoidance (falls back to a direct connector if no path " \
+                   "is found within the search limit)",
       category: "routing",
       supports_hierarchy: false,
     },
@@ -248,8 +273,8 @@ module Elkrb
     Layout::Algorithms::VertiFlex,
     {
       name: "VertiFlex",
-      description: "Vertical flexible layout with column-based arrangement",
-      category: "layered",
+      description: "Column-grid arrangement that ignores edges",
+      category: "packing",
       supports_hierarchy: false,
       experimental: true,
     },
@@ -261,11 +286,27 @@ module Elkrb
   # a Graph model object and applies the chosen layout algorithm to compute
   # node positions and edge routes.
   #
+  # A Graph argument is mutated in place and returned, so the caller's object
+  # carries the computed positions. A Hash argument is converted to a fresh
+  # Graph and left untouched.
+  #
   # @param graph [Hash, Graph::Graph] The graph to layout
+  # Options are read in one order: the graph's own layoutOptions, then its
+  # properties, then these call-level options, then the registry default. A
+  # graph that pins an algorithm keeps it, whatever :algorithm says here.
+  #
   # @param options [Hash] Layout options including:
-  #   - :algorithm (String) - Algorithm name (default: "layered")
+  #   - :algorithm (String) - Algorithm name, used when the graph pins none
+  #     (default: "layered")
+  #   - :strict (Boolean) - Raise instead of warn when the graph carries an
+  #     option elkrb does not know or does not fully honour, or the call
+  #     passes a registered option that is not fully honoured (default: false)
   #   - Algorithm-specific options (e.g., "elk.spacing.nodeNode")
   # @return [Graph::Graph] The input graph with computed positions
+  # @raise [ArgumentError] If graph is neither a Hash nor a Graph::Graph
+  # @raise [Elkrb::AlgorithmNotFoundError] If the algorithm is not registered
+  # @raise [Elkrb::ValidationError] If an option value has the wrong type
+  # @raise [Elkrb::Error] In strict mode, for an unknown or unhonoured option
   #
   # @example With hash input
   #   result = Elkrb.layout({
@@ -357,7 +398,7 @@ module Elkrb
 
   # Returns metadata for all available layout algorithms.
   #
-  # This includes the 12 built-in algorithms plus any custom algorithms
+  # This includes the built-in algorithms plus any custom algorithms
   # registered via {register_algorithm}.
   #
   # @return [Array<Hash>] Array of algorithm metadata with keys:
@@ -366,6 +407,7 @@ module Elkrb
   #   - :description (String) - Brief description
   #   - :category (String) - Algorithm category
   #   - :supports_hierarchy (Boolean) - Whether it supports nested graphs
+  #   - :supported_options (Array<String>) - Canonical option ids scoped to this algorithm
   #
   # @example List all algorithms
   #   Elkrb.known_layout_algorithms.each do |alg|
@@ -376,29 +418,22 @@ module Elkrb
   #   force_algorithms = Elkrb.known_layout_algorithms
   #     .select { |alg| alg[:category] == "force" }
   def self.known_layout_algorithms
-    Layout::AlgorithmRegistry.all.map do |name, data|
-      {
-        id: name,
-        name: data[:metadata][:name] || name.capitalize,
-        description: data[:metadata][:description] || "",
-        category: data[:metadata][:category] || "general",
-        supports_hierarchy: data[:metadata][:supports_hierarchy] || false,
-      }
-    end
+    Layout::AlgorithmRegistry.all_algorithm_info
   end
 
-  # Returns metadata for all supported layout options.
+  # Returns metadata for all supported layout options, sourced from
+  # Elkrb::Options::Registry (the single source of truth every algorithm
+  # and the CLI eventually read from).
   #
-  # This includes common options like algorithm selection, spacing,
-  # direction, and padding, as well as algorithm-specific options.
-  #
-  # @return [Hash{String => Hash}] Hash mapping option names to metadata.
+  # @return [Hash{String => Hash}] Hash mapping canonical option ids to metadata.
   #   Each metadata hash contains:
-  #   - :type (String) - Option value type
+  #   - :type (Symbol) - Option value type (:string, :float, :integer,
+  #     :boolean, :enum, :padding, :kvector, :kvector_chain)
   #   - :description (String) - Brief description
   #   - :default - Default value
   #   - :values (Array, nil) - Allowed values for enum types
   #   - :parser (String, nil) - Parser class for complex types
+  #   - :status (Symbol) - :honoured, :partial, :accepted, or :unsupported
   #
   # @example Query options
   #   options = Elkrb.known_layout_options
@@ -407,45 +442,9 @@ module Elkrb
   #
   # @example Get allowed values
   #   directions = Elkrb.known_layout_options["elk.direction"][:values]
-  #   # => ["UP", "DOWN", "LEFT", "RIGHT"]
+  #   # => ["UNDEFINED", "RIGHT", "LEFT", "DOWN", "UP"]
   def self.known_layout_options
-    {
-      "algorithm" => {
-        type: "string",
-        description: "The layout algorithm to use",
-        default: "layered",
-        values: Layout::AlgorithmRegistry.all.keys,
-      },
-      "elk.direction" => {
-        type: "string",
-        description: "Overall direction of layout",
-        default: "RIGHT",
-        values: %w[UP DOWN LEFT RIGHT],
-      },
-      "elk.spacing.nodeNode" => {
-        type: "float",
-        description: "Spacing between nodes",
-        default: 20.0,
-      },
-      "elk.padding" => {
-        type: "ElkPadding",
-        description: "Padding around the graph",
-        default: "[left=12, top=12, right=12, bottom=12]",
-        parser: "Elkrb::Options::ElkPadding",
-      },
-      "position" => {
-        type: "KVector",
-        description: "Fixed position for nodes (when using fixed algorithm)",
-        default: nil,
-        parser: "Elkrb::Options::KVector",
-      },
-      "bendPoints" => {
-        type: "KVectorChain",
-        description: "Bend points for edges",
-        default: nil,
-        parser: "Elkrb::Options::KVectorChain",
-      },
-    }
+    Options::Registry.render_known_options(algorithm_values: Layout::AlgorithmRegistry.available_algorithms)
   end
 
   # Returns metadata for layout option categories.

metadata

@@ -1,43 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: elkrb
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-14 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.7'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+        version: '0.8'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.7'
-- !ruby/object:Gem::Dependency
-  name: rbs
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -54,7 +46,7 @@ dependencies:
         version: '1.4'
 description: |
   Pure Ruby implementation of the Eclipse Layout Kernel (ELK) providing automatic
-  layout of node-link diagrams. Supports all ELK algorithms.
+  layout of node-link diagrams. Supports 15 registered layout algorithms.
 email:
 - open.source@ribose.com
 executables:
@@ -62,48 +54,38 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
-- Gemfile
+- CHANGELOG.adoc
+- LICENSE
 - README.adoc
-- Rakefile
-- benchmarks/README.md
-- benchmarks/elkjs_benchmark.js
-- benchmarks/elkrb_benchmark.rb
-- benchmarks/fixtures/graphs.json
-- benchmarks/generate_report.rb
-- benchmarks/generate_test_graphs.rb
-- benchmarks/results/elkrb_results.json
-- benchmarks/results/elkrb_summary.json
-- elkrb.gemspec
-- examples/dot_export_demo.rb
-- examples/hierarchical_graph.rb
-- examples/layout_constraints_demo.rb
-- examples/port_constraints_demo.rb
-- examples/self_loop_demo.rb
-- examples/simple_graph.rb
-- examples/spline_routing_demo.rb
 - exe/elkrb
 - lib/elkrb.rb
+- lib/elkrb/atomic_destination.rb
+- lib/elkrb/best_effort_write.rb
 - lib/elkrb/cli.rb
+- lib/elkrb/cli/layout_flag_options.rb
+- lib/elkrb/command_resolver.rb
 - lib/elkrb/commands/batch_command.rb
 - lib/elkrb/commands/convert_command.rb
 - lib/elkrb/commands/diagram_command.rb
+- lib/elkrb/commands/options_command.rb
 - lib/elkrb/commands/render_command.rb
 - lib/elkrb/commands/validate_command.rb
 - lib/elkrb/errors.rb
+- lib/elkrb/format_sniffer.rb
 - lib/elkrb/geometry/bezier.rb
 - lib/elkrb/geometry/dimension.rb
 - lib/elkrb/geometry/point.rb
 - lib/elkrb/geometry/rectangle.rb
 - lib/elkrb/geometry/vector.rb
+- lib/elkrb/graph/deep_stringify_keys.rb
 - lib/elkrb/graph/edge.rb
 - lib/elkrb/graph/graph.rb
 - lib/elkrb/graph/label.rb
-- lib/elkrb/graph/layout_options.rb
 - lib/elkrb/graph/node.rb
 - lib/elkrb/graph/node_constraints.rb
+- lib/elkrb/graph/normalize_option_keys.rb
 - lib/elkrb/graph/port.rb
+- lib/elkrb/graph/read_only_mapping.rb
 - lib/elkrb/graphviz_wrapper.rb
 - lib/elkrb/layout/algorithm_registry.rb
 - lib/elkrb/layout/algorithms/base_algorithm.rb
@@ -112,9 +94,26 @@ files:
 - lib/elkrb/layout/algorithms/fixed.rb
 - lib/elkrb/layout/algorithms/force.rb
 - lib/elkrb/layout/algorithms/layered.rb
+- lib/elkrb/layout/algorithms/layered/bk/aligner.rb
+- lib/elkrb/layout/algorithms/layered/bk/compactor.rb
+- lib/elkrb/layout/algorithms/layered/bk/view.rb
+- lib/elkrb/layout/algorithms/layered/bk_node_placer.rb
+- lib/elkrb/layout/algorithms/layered/components.rb
+- lib/elkrb/layout/algorithms/layered/crossing_minimizer.rb
 - lib/elkrb/layout/algorithms/layered/cycle_breaker.rb
+- lib/elkrb/layout/algorithms/layered/discovery_order.rb
+- lib/elkrb/layout/algorithms/layered/dummy_slot.rb
 - lib/elkrb/layout/algorithms/layered/layer_assigner.rb
+- lib/elkrb/layout/algorithms/layered/layer_constraints.rb
+- lib/elkrb/layout/algorithms/layered/layer_sweep.rb
 - lib/elkrb/layout/algorithms/layered/node_placer.rb
+- lib/elkrb/layout/algorithms/layered/orthogonal/gap_solver.rb
+- lib/elkrb/layout/algorithms/layered/orthogonal/hyper_edge_segment.rb
+- lib/elkrb/layout/algorithms/layered/orthogonal/junction_points.rb
+- lib/elkrb/layout/algorithms/layered/orthogonal/segment_order.rb
+- lib/elkrb/layout/algorithms/layered/orthogonal_router.rb
+- lib/elkrb/layout/algorithms/layered/port_order.rb
+- lib/elkrb/layout/algorithms/layered/port_spread.rb
 - lib/elkrb/layout/algorithms/libavoid.rb
 - lib/elkrb/layout/algorithms/mrtree.rb
 - lib/elkrb/layout/algorithms/radial.rb
@@ -133,29 +132,52 @@ files:
 - lib/elkrb/layout/constraints/relative_position_constraint.rb
 - lib/elkrb/layout/edge_router.rb
 - lib/elkrb/layout/hierarchical_processor.rb
+- lib/elkrb/layout/java_random.rb
 - lib/elkrb/layout/label_placer.rb
 - lib/elkrb/layout/layout_engine.rb
+- lib/elkrb/layout/node_index.rb
+- lib/elkrb/layout/polyomino/component_compactor.rb
+- lib/elkrb/layout/polyomino/footprint.rb
+- lib/elkrb/layout/polyomino/grid.rb
+- lib/elkrb/layout/polyomino/packer.rb
+- lib/elkrb/layout/polyomino/piece.rb
 - lib/elkrb/layout/port_constraint_processor.rb
+- lib/elkrb/layout/spore/body.rb
+- lib/elkrb/layout/spore/depth_first_compaction.rb
+- lib/elkrb/layout/spore/edge_cost.rb
+- lib/elkrb/layout/spore/gap.rb
+- lib/elkrb/layout/spore/geometry.rb
+- lib/elkrb/layout/spore/overlap_sweep.rb
+- lib/elkrb/layout/spore/placement.rb
+- lib/elkrb/layout/spore/rays.rb
+- lib/elkrb/layout/spore/spanning_tree.rb
+- lib/elkrb/layout/spore/triangulation.rb
+- lib/elkrb/layout_flags.rb
+- lib/elkrb/options/decimal.rb
+- lib/elkrb/options/element_options.rb
 - lib/elkrb/options/elk_padding.rb
 - lib/elkrb/options/k_vector.rb
 - lib/elkrb/options/k_vector_chain.rb
+- lib/elkrb/options/option_map.rb
+- lib/elkrb/options/registry.rb
+- lib/elkrb/options/resolver.rb
+- lib/elkrb/options/spellings.rb
+- lib/elkrb/options/unhonoured_report.rb
+- lib/elkrb/parsers/elkt/lexer.rb
+- lib/elkrb/parsers/elkt/parser.rb
+- lib/elkrb/parsers/elkt/resolver.rb
+- lib/elkrb/parsers/elkt/token.rb
 - lib/elkrb/parsers/elkt_parser.rb
 - lib/elkrb/serializers/dot_serializer.rb
 - lib/elkrb/serializers/elkt_serializer.rb
 - lib/elkrb/version.rb
-- sig/elkrb.rbs
-- sig/elkrb/constraints.rbs
-- sig/elkrb/geometry.rbs
-- sig/elkrb/graph.rbs
-- sig/elkrb/layout.rbs
-- sig/elkrb/options.rbs
 homepage: https://github.com/claricle/elkrb
 licenses:
 - BSD-2-Clause
 metadata:
   homepage_uri: https://github.com/claricle/elkrb
   source_code_uri: https://github.com/claricle/elkrb
-  changelog_uri: https://github.com/claricle/elkrb
+  changelog_uri: https://github.com/claricle/elkrb/blob/v2/CHANGELOG.adoc
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -165,7 +187,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.rspec

@@ -1,3 +0,0 @@
---require spec_helper
---color
---format documentation

data/.rubocop.yml

@@ -1,11 +0,0 @@
-# Auto-generated by Cimas: Do not edit it manually!
-# See https://github.com/metanorma/cimas
-inherit_from:
-  - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
-  - .rubocop_todo.yml
-
-# local repo-specific modifications
-# ...
-
-AllCops:
-  NewCops: enable

data/Gemfile

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in omnizip.gemspec
-gemspec
-
-gem "rake"
-gem "rspec"
-gem "rubocop"
-gem "rubocop-performance"
-gem "rubocop-rake"
-gem "rubocop-rspec"

data/Rakefile

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec
-
-namespace :benchmark do
-  desc "Generate test graphs for benchmarking"
-  task :generate_graphs do
-    ruby "benchmarks/generate_test_graphs.rb"
-  end
-
-  desc "Run ElkRb benchmarks"
-  task elkrb: :generate_graphs do
-    ruby "benchmarks/elkrb_benchmark.rb"
-  end
-
-  desc "Run elkjs benchmarks (requires Node.js and elkjs)"
-  task elkjs: :generate_graphs do
-    sh "node benchmarks/elkjs_benchmark.js"
-  end
-
-  desc "Generate performance report"
-  task :report do
-    ruby "benchmarks/generate_report.rb"
-  end
-
-  desc "Run all benchmarks and generate report"
-  task all: %i[elkrb report] do
-    puts "\nAll benchmarks completed!"
-    puts "Note: Run 'rake benchmark:elkjs' separately if elkjs is installed"
-  end
-end
-
-namespace :validate do
-  desc "Import test cases from elkjs"
-  task :import_elkjs do
-    ruby "spec/cross_validation/elkjs_test_importer.rb"
-  end
-
-  desc "Import test cases from Java ELK"
-  task :import_java_elk do
-    ruby "spec/cross_validation/java_elk_test_importer.rb"
-  end
-
-  desc "Import all test cases from elkjs and Java ELK"
-  task import_all: %i[import_elkjs import_java_elk]
-
-  desc "Run cross-validation tests"
-  task :run do
-    ruby "spec/cross_validation/validation_runner.rb"
-  end
-
-  desc "Import and run cross-validation (full pipeline)"
-  task all: %i[import_all run]
-
-  desc "Generate validation report (AsciiDoc)"
-  task :report do
-    ruby "spec/cross_validation/generate_validation_report.rb"
-  end
-end