Class: Toml::Merge::SmartMerger

Inherits:
Ast::Merge::SmartMergerBase
  • Object
show all
Includes:
Ast::Merge::Runtime::RootSessionSupport
Defined in:
lib/toml/merge/smart_merger.rb

Overview

High-level merger for TOML content. Orchestrates parsing, analysis, and conflict resolution.

Extends SmartMergerBase with backend-agnostic parsing via tree_haver. Supports both tree-sitter and Citrus/toml-rb backends (auto-selected by TreeHaver).

Examples:

Basic usage

merger = SmartMerger.new(template_content, dest_content)
result = merger.merge
File.write("merged.toml", result.output)

Force Citrus backend via environment

# Set TREE_HAVER_BACKEND=citrus before requiring toml/merge
merger = SmartMerger.new(template, dest)
result = merger.merge

Force Citrus backend via TreeHaver

TreeHaver.with_backend(:citrus) do
  merger = SmartMerger.new(template, dest)
  result = merger.merge
end

With options

merger = SmartMerger.new(template, dest,
  preference: :template,
  add_template_only_nodes: true)
result = merger.merge

Enable fuzzy matching

merger = SmartMerger.new(template, dest, match_refiner: TableMatchRefiner.new)

With regions (embedded content)

merger = SmartMerger.new(template, dest,
  regions: [{ detector: SomeDetector.new, merger_class: SomeMerger }])

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(template_content, dest_content, signature_generator: nil, preference: :destination, add_template_only_nodes: false, remove_template_missing_nodes: false, corruption_handling: :heal, freeze_token: nil, match_refiner: nil, regions: nil, region_placeholder: nil, node_typing: nil, sort_keys: false, **options) ⇒ SmartMerger

Note:

To force a specific backend, use TreeHaver.with_backend or TREE_HAVER_BACKEND env var. TreeHaver handles backend selection, auto-detection, and fallback.

Creates a new SmartMerger

Parameters:

  • template_content (String) —

    Template TOML content

  • dest_content (String) —

    Destination TOML content

  • signature_generator (Proc, nil) (defaults to: nil) —

    Custom signature generator

  • preference (Symbol, Hash) (defaults to: :destination) —

    :destination, :template, or per-type Hash

  • add_template_only_nodes (Boolean) (defaults to: false) —

    Whether to add nodes only found in template

  • freeze_token (String, nil) (defaults to: nil) —

    Token for freeze block markers

  • match_refiner (#call, nil) (defaults to: nil) —

    Match refiner for fuzzy matching

  • remove_template_missing_nodes (Boolean) (defaults to: false) —

    Whether to remove destination-only nodes while preserving their attached comments

  • regions (Array<Hash>, nil) (defaults to: nil) —

    Region configurations for nested merging

  • region_placeholder (String, nil) (defaults to: nil) —

    Custom placeholder for regions

  • node_typing (Hash{Symbol,String => #call}, nil) (defaults to: nil) —

    Node typing configuration for per-node-type merge preferences

  • sort_keys (Boolean) (defaults to: false) —

    Whether to alphabetically sort key=value pairs within gap-separated blocks after merging

  • options (Hash) —

    Additional options for forward compatibility



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/toml/merge/smart_merger.rb', line 72

def initialize(
  template_content,
  dest_content,
  signature_generator: nil,
  preference: :destination,
  add_template_only_nodes: false,
  remove_template_missing_nodes: false,
  corruption_handling: :heal,
  freeze_token: nil,
  match_refiner: nil,
  regions: nil,
  region_placeholder: nil,
  node_typing: nil,
  sort_keys: false,
  **options
)
  @remove_template_missing_nodes = remove_template_missing_nodes
  @corruption_handling = ::Ast::Merge::Healer.normalize_mode(corruption_handling)
  @sort_keys = sort_keys

  super(
    template_content,
    dest_content,
    signature_generator: signature_generator,
    preference: preference,
    add_template_only_nodes: add_template_only_nodes,
    remove_template_missing_nodes: remove_template_missing_nodes,
    freeze_token: freeze_token,
    match_refiner: match_refiner,
    regions: regions,
    region_placeholder: region_placeholder,
    node_typing: node_typing,
    **options
  )

  # Capture the resolved backend from template analysis (for NodeTypeNormalizer)
  @backend = @template_analysis.backend
end

Instance Attribute Details

#backend ⇒ Symbol (readonly)

Returns The AST format being used (:tree_sitter or :citrus).

Returns:

  • (Symbol) —

    The AST format being used (:tree_sitter or :citrus)



45
46
47
 
# File 'lib/toml/merge/smart_merger.rb', line 45

def backend
  @backend
end

#corruption_handling ⇒ Object (readonly)

Returns the value of attribute corruption_handling.



42
43
44
 
# File 'lib/toml/merge/smart_merger.rb', line 42

def corruption_handling
  @corruption_handling
end

#remove_template_missing_nodes ⇒ Boolean (readonly)

Returns Whether destination-only nodes should be removed while promoting their attached comments.

Returns:

  • (Boolean) —

    Whether destination-only nodes should be removed while promoting their attached comments



49
50
51
 
# File 'lib/toml/merge/smart_merger.rb', line 49

def remove_template_missing_nodes
  @remove_template_missing_nodes
end

#runtime_session ⇒ Object (readonly)

Returns the value of attribute runtime_session.



42
43
44
 
# File 'lib/toml/merge/smart_merger.rb', line 42

def runtime_session
  @runtime_session
end

Instance Method Details

#merge_result ⇒ MergeResult

Perform the merge operation and return the full MergeResult object.

Returns:

  • (MergeResult) —

    The merge result containing merged TOML content and metadata



129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/toml/merge/smart_merger.rb', line 129

def merge_result
  return @merge_result if @merge_result

  root_operation = start_runtime_session!
  @merge_result = super
  complete_runtime_session!(root_operation, @merge_result)
  @merge_result
rescue StandardError => e
  fail_runtime_session!(root_operation, e)
  raise
end

#merge_with_debug ⇒ Hash

Perform the merge and return detailed runtime-aware debug information.

Returns:

  • (Hash) —

    Hash containing :content, :debug, :runtime, :statistics, and :decisions



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/toml/merge/smart_merger.rb', line 144

def merge_with_debug
  result_obj = merge_result
  template_analysis_debug = {
    valid: @template_analysis.valid?,
    statements: @template_analysis.statements.size
  }
  dest_analysis_debug = {
    valid: @dest_analysis.valid?,
    statements: @dest_analysis.statements.size
  }

  {
    content: result_obj.to_toml,
    debug: {
      template_statements: template_analysis_debug[:statements],
      dest_statements: dest_analysis_debug[:statements],
      preference: @preference,
      add_template_only_nodes: @add_template_only_nodes,
      remove_template_missing_nodes: @remove_template_missing_nodes,
      resolution_mode: @resolution_mode,
      corruption_handling: @corruption_handling,
      freeze_token: @freeze_token,
      sort_keys: @sort_keys,
      backend: @backend,
      runtime_operation_count: runtime_session&.operations&.size || 0,
      runtime_diagnostic_count: runtime_session&.diagnostics&.size || 0
    },
    runtime: runtime_session&.to_h,
    statistics: result_obj.statistics,
    decisions: result_obj.decision_summary,
    template_analysis: template_analysis_debug,
    dest_analysis: dest_analysis_debug
  }
end

#options ⇒ Hash

Backward-compatible options hash

Returns:

  • (Hash) —

    The merge options



114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/toml/merge/smart_merger.rb', line 114

def options
  {
    preference: @preference,
    add_template_only_nodes: @add_template_only_nodes,
    remove_template_missing_nodes: @remove_template_missing_nodes,
    resolution_mode: @resolution_mode,
    unresolved_policy: @unresolved_policy.to_h,
    corruption_handling: @corruption_handling,
    match_refiner: @match_refiner
  }
end