ecoportal-api-graphql 1.3.10 → 1.3.12

data/lib/ecoportal/api/graphql/concerns/page_compat.rb

@@ -1,51 +1,51 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Concerns
-        # v2-compatibility accessors for page model objects.
-        # Include in Interface::BasePage so all concrete page classes inherit them.
-        # These aliases allow eco-helpers scripts to work against GraphQL page models
-        # using the same method names they used with ecoportal-api-v2.
-        module PageCompat
-          # v2 called this externalId (camelCase) or external_id (snake_case)
-          def external_id
-            externalId
-          end
-
-          # v2 called sourceTemplateId "template_id"
-          def template_id
-            sourceTemplateId
-          end
-
-          # v2 compatibility: dataFields were called "components" in APIv2
-          def components
-            respond_to?(:dataFields) ? dataFields : []
-          end
-
-          # Whether the page has any stages (PhasedPage check)
-          def stages?
-            respond_to?(:stages) && !stages.nil? && !stages.empty?
-          end
-
-          # Clears dirty tracking — call after a successful update.
-          # Mirrors v2's ooze.consolidate! which resets the change baseline.
-          def consolidate!
-            @original_doc = doc.dup if respond_to?(:doc)
-            self
-          end
-
-          # v2 validate stub — always returns nil (no client-side validation in GraphQL path).
-          # Server-side errors are returned in the mutation payload's errors field.
-          def validate
-            nil
-          end
-
-          # Dirty check — returns true if there are pending changes.
-          def dirty?
-            !as_update.nil?
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Concerns
+        # v2-compatibility accessors for page model objects.
+        # Include in Interface::BasePage so all concrete page classes inherit them.
+        # These aliases allow eco-helpers scripts to work against GraphQL page models
+        # using the same method names they used with ecoportal-api-v2.
+        module PageCompat
+          # v2 called this externalId (camelCase) or external_id (snake_case)
+          def external_id
+            externalId
+          end
+
+          # v2 called sourceTemplateId "template_id"
+          def template_id
+            sourceTemplateId
+          end
+
+          # v2 compatibility: dataFields were called "components" in APIv2
+          def components
+            respond_to?(:dataFields) ? dataFields : []
+          end
+
+          # Whether the page has any stages (PhasedPage check)
+          def stages?
+            respond_to?(:stages) && !stages.nil? && !stages.empty?
+          end
+
+          # Clears dirty tracking — call after a successful update.
+          # Mirrors v2's ooze.consolidate! which resets the change baseline.
+          def consolidate!
+            @original_doc = doc.dup if respond_to?(:doc)
+            self
+          end
+
+          # v2 validate stub — always returns nil (no client-side validation in GraphQL path).
+          # Server-side errors are returned in the mutation payload's errors field.
+          def validate
+            nil
+          end
+
+          # Dirty check — returns true if there are pending changes.
+          def dirty?
+            !as_update.nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/concerns.rb

@@ -1,14 +1,14 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Concerns
-      end
-    end
-  end
-end
-
-require_relative 'concerns/deprecation'
-require_relative 'concerns/fragment_definitions'
-require_relative 'concerns/snake_camel_access'
-require_relative 'concerns/page_compat'
-require_relative 'concerns/data_field_access'
+module Ecoportal
+  module API
+    class GraphQL
+      module Concerns
+      end
+    end
+  end
+end
+
+require_relative 'concerns/deprecation'
+require_relative 'concerns/fragment_definitions'
+require_relative 'concerns/snake_camel_access'
+require_relative 'concerns/page_compat'
+require_relative 'concerns/data_field_access'

data/lib/ecoportal/api/graphql/diff/change.rb

@@ -0,0 +1,59 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # One structural change between two snapshots of the same page/template.
+        #
+        # Deliberately command-ready: op + kind + id + before/after is enough for a later pass to
+        # synthesise the matching WorkflowCommand (editStage / addField / removeField /
+        # editFieldConfiguration / addSelectFieldOption / …) — the "portable commit".
+        #
+        # op:   :added | :removed | :changed | :moved
+        # kind: :stage | :section | :field | :option | :field_config | :gauge_stop
+        #
+        # parent_id: id of the owning entity when the change is nested and the child id alone is
+        # not enough to address a command. Set for :option changes (the parent data field id) so a
+        # synthesiser can emit add/edit/removeSelectFieldOption without re-deriving it; also for
+        # :field_config (the data field id) and :gauge_stop (the gauge field id).
+        #
+        # by_type: for :field_config changes, the `byType` sub-hash key (e.g. :gauge, :select, :date)
+        # under which the typed editFieldConfiguration property is nested. nil for other kinds.
+        #
+        # owner_id: the id of the GRANDPARENT node, when a create needs a second structural back-ref
+        # that parent_id alone cannot carry. Set for an ADDED :field (parent_id = its section id,
+        # owner_id = its stage id) because addField requires BOTH sectionId and stageId (both
+        # NON_NULL in the schema). nil for every other kind/op.
+        Change = Struct.new(:op, :kind, :id, :label, :path, :attribute, :before, :after, :parent_id,
+                            :by_type, :owner_id, keyword_init: true) do
+          def to_h
+            {
+              op: op, kind: kind, id: id, label: label, path: path,
+              attribute: attribute, before: before, after: after, parent_id: parent_id,
+              by_type: by_type, owner_id: owner_id
+            }.compact
+          end
+
+          # One-line human description for a changelog / ticket comment.
+          def description
+            case op
+            when :added   then "+ #{kind} '#{label}' added#{at_path}"
+            when :removed then "- #{kind} '#{label}' removed#{at_path}"
+            when :changed then "~ #{kind} '#{label}' #{attribute}: #{fmt(before)} -> #{fmt(after)}#{at_path}"
+            when :moved   then "> #{kind} '#{label}' moved: #{fmt(before)} -> #{fmt(after)}"
+            end
+          end
+
+          private
+
+          def at_path
+            path && !path.empty? ? "  (#{path})" : ''
+          end
+
+          def fmt(value)
+            value.nil? ? 'nil' : value.inspect
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/diff/command_synthesizer.rb

@@ -0,0 +1,329 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # Turns a set of `Diff::Change` objects (from `VersionDiff`) into an ordered batch of built
+        # `WorkflowCommand` hashes — the replayable "commit".
+        #
+        #   changes  = VersionDiff.new(v1, v2).changes
+        #   synth    = CommandSynthesizer.new(changes)
+        #   synth.commands     # => [{ editFieldConfiguration: {...} }, { removeField: {...} }, ...]
+        #   synth.unsupported  # => [Change, ...]  (change kinds/ops with no matching command)
+        #
+        # SCOPE — self-version diff by default. The ids carried by each Change are REAL server ids of
+        # the SAME object across two of its own versions, so they can be replayed as-is. For a
+        # cross-object diff (UAT<->PROD, page<->template) every id in the emitted commands must first
+        # be translated through a pairing map before replay.
+        #
+        # RESOLVER — some edits address a TARGET node by an id the Change does not carry (a field
+        # move needs the destination *section id*; a section move needs the destination *stage id*).
+        # `VersionDiff` records those targets by their human key (section heading, stage name) because
+        # that is all a structural diff knows. Pass a `resolver` that maps
+        # `resolve(kind, key) => id` (e.g. the pairing engine's ledger, or a lookup built from the
+        # target doc) and those moves become supported. WITHOUT a resolver they stay UNSUPPORTED —
+        # the synthesiser never guesses a target id.
+        #
+        # ORDERING — structure before children, and within a kind: removes, then adds, then moves,
+        # then edits. Structural creates (stages, sections, fields) precede the option-level edits
+        # that depend on them, so a straight left-to-right replay stays valid.
+        #
+        # SAFETY — a change with no faithful command is NEVER guessed. It is collected into
+        # `unsupported` for the caller to inspect. In particular a field *type* change has no edit
+        # command in the schema (there is no editFieldType), so it is reported as unsupported rather
+        # than silently rebuilt (a rebuild would drop the field's data and history).
+        class CommandSynthesizer
+          # Emit order: structure first (stages -> sections -> fields), then options; and within a
+          # kind, removes -> adds -> moves -> edits, so a straight left-to-right replay stays valid.
+          KIND_ORDER = { stage: 0, section: 1, field: 2, field_config: 3, gauge_stop: 4, option: 5 }.freeze
+          OP_ORDER   = { removed: 0, added: 1, moved: 2, changed: 3 }.freeze
+
+          # @param changes  [Array<Change>]
+          # @param resolver [#resolve, nil] maps (kind, human-key) -> target id for move commands.
+          #   Any object answering `resolve(kind, key)` (returning an id or nil). When nil, moves
+          #   that need a target id are reported as unsupported.
+          # @param thread_placeholders [Boolean] when true, structural creates (addStage/addSection/
+          #   addField) emit a client-chosen `placeholderId`, and any later command in the SAME batch
+          #   that references a node created here substitutes that placeholder for the (target-invalid)
+          #   source id. This keeps add-then-reference sequences self-consistent within one
+          #   executeWorkflowCommands call. Off by default (self-version replay uses the real ids).
+          def initialize(changes, resolver: nil, thread_placeholders: false)
+            @changes             = Array(changes)
+            @resolver            = resolver
+            @thread_placeholders = thread_placeholders
+            @unsupported         = []
+          end
+
+          # Ordered Array of built command hashes (each `{ commandKey => {..input..} }`).
+          def commands
+            @commands ||= build_all
+          end
+
+          # Changes that could not be mapped to a command. Populated as a side effect of `commands`.
+          def unsupported
+            commands
+            @unsupported
+          end
+
+          private
+
+          # Group by (kind, op) and emit in a dependency-safe order:
+          # stages -> sections -> fields -> options, and remove -> add -> move -> change within each.
+          def build_all
+            build_placeholder_map
+            ordered = @changes.sort_by { |c| [KIND_ORDER.fetch(c.kind, 99), OP_ORDER.fetch(c.op, 99)] }
+            # command_for may return a single built hash, an Array of them (a move that emits
+            # remove+add), or nil (unsupported). Normalise each to a list, flatten, drop nils.
+            ordered.flat_map { |change| wrap(command_for(change)) }
+          end
+
+          # When threading is on, assign a deterministic placeholderId to every ADDED structural
+          # node (stage/section/field), keyed by its source id. A later command in this batch that
+          # references such an id is rewritten to the placeholder (the source id is not valid on the
+          # target). Threading OFF -> empty map -> `ref`/`placeholder_for` are no-ops.
+          def build_placeholder_map
+            @placeholders = {}
+            return unless @thread_placeholders
+
+            prefixes = { stage: 'stg', section: 'sec', field: 'fld' }
+            @changes.select { |c| c.op == :added && prefixes.key?(c.kind) }.each_with_index do |change, i|
+              next if change.id.nil?
+
+              @placeholders[change.id] = "ph_#{prefixes[change.kind]}_#{i}"
+            end
+          end
+
+          # The placeholder token for a node created in THIS batch, or nil if it was not.
+          def placeholder_for(id)
+            @placeholders[id]
+          end
+
+          # Reference an id the way a sibling command must: the batch-local placeholder if the node
+          # is being created here, otherwise the id as-is (a pre-existing target node).
+          def ref(id)
+            placeholder_for(id) || id
+          end
+
+          def command_for(change)
+            case change.kind
+            when :stage        then stage_command(change)
+            when :section      then section_command(change)
+            when :field        then field_command(change)
+            when :field_config then field_config_command(change)
+            when :gauge_stop   then gauge_stop_command(change)
+            when :option       then option_command(change)
+            else unsupported!(change)
+            end
+          end
+
+          # --- stage ---------------------------------------------------------
+
+          def stage_command(change)
+            case change.op
+            when :added   then build(:addStage, name: change.label, placeholderId: placeholder_for(change.id))
+            when :removed then build(:removeStage, stageId: change.id)
+            when :moved   then build(:moveStage, stageId: change.id, ordering: change.after)
+            when :changed
+              return build(:editStage, stageId: change.id, name: change.after) if change.attribute == 'name'
+
+              unsupported!(change)
+            else unsupported!(change)
+            end
+          end
+
+          # --- section -------------------------------------------------------
+
+          def section_command(change)
+            case change.op
+            when :added   then add_section(change)
+            when :removed then build(:removeSection, sectionId: change.id)
+            when :moved   then section_move(change)
+            when :changed
+              return build(:editSectionHeader, sectionId: change.id, header: change.after) if change.attribute == 'heading'
+
+              unsupported!(change)
+            else unsupported!(change)
+            end
+          end
+
+          # An added section is created with addSection (layout/placeholder), then WIRED to its
+          # parent stage with a follow-up addStageSection — addSection itself has no stage-id key in
+          # the schema, the stage<->section link is a separate command. The stage back-ref threads
+          # through `ref`: the parent stage's placeholder when it is created in this same batch, else
+          # its real id. When the parent stage id is unknown (a hand-assembled Change with no
+          # parent_id), only addSection is emitted — the historical behaviour, unchanged.
+          def add_section(change)
+            cmds = [build(:addSection, placeholderId: placeholder_for(change.id))]
+            cmds << build(:addStageSection, stageId: ref(change.parent_id), sectionId: ref(change.id)) unless change.parent_id.nil?
+            cmds
+          end
+
+          # A section 'move' is a stage reassignment: detach from the old stage, attach to the new.
+          # Both need a stage id; VersionDiff records only the stage NAME (before/after), so a
+          # resolver is required to turn those names into ids. Emitted as two commands so the replay
+          # is faithful (remove then add). Without a resolver -> unsupported (never guess a stage id).
+          def section_move(change)
+            return unsupported!(change) if change.attribute != 'stage'
+
+            from_id = resolve(:stage, change.before)
+            to_id   = resolve(:stage, change.after)
+            return unsupported!(change) if to_id.nil?
+
+            cmds = []
+            cmds << build(:removeStageSection, stageId: from_id, sectionId: change.id) if from_id
+            cmds << build(:addStageSection, stageId: to_id, sectionId: change.id)
+            cmds
+          end
+
+          # --- field ---------------------------------------------------------
+
+          def field_command(change)
+            case change.op
+            when :added   then add_field(change)
+            when :removed then build(:removeField, id: change.id)
+            when :moved   then field_move(change)
+            when :changed then field_edit(change)
+            else unsupported!(change)
+            end
+          end
+
+          # An added field carries its structural back-refs: sectionId (parent_id) and stageId
+          # (owner_id) — both NON_NULL on the schema's addField input. Each threads through `ref`:
+          # the parent's placeholder when the parent stage/section is created in this same batch,
+          # else its real id. When a back-ref id is unknown (a hand-assembled Change without
+          # parent_id/owner_id) that key is simply omitted (AddField.build compacts nils) — the
+          # historical behaviour, unchanged.
+          def add_field(change)
+            build(:addField,
+                  label:         change.label,
+                  sectionId:     (ref(change.parent_id) unless change.parent_id.nil?),
+                  stageId:       (ref(change.owner_id) unless change.owner_id.nil?),
+                  placeholderId: placeholder_for(change.id))
+          end
+
+          def field_edit(change)
+            return build(:editFieldConfiguration, data_field_id: change.id, label: change.after) if change.attribute == 'label'
+
+            # Field TYPE change: no editFieldType command exists in the schema. Do not synthesise a
+            # remove+add (it would destroy the field's data) — report it for manual handling.
+            unsupported!(change)
+          end
+
+          # A field 'move' is a section reassignment. moveField needs the destination SECTION id;
+          # VersionDiff records only the section HEADING (before/after). A resolver turns the target
+          # heading into a section id. Without one -> unsupported (never guess a section id).
+          def field_move(change)
+            return unsupported!(change) if change.attribute != 'section'
+
+            section_id = resolve(:section, change.after)
+            return unsupported!(change) if section_id.nil?
+
+            build(:moveField, id: change.id, sectionId: section_id)
+          end
+
+          # --- typed field configuration (byType) ----------------------------
+
+          # A per-type field-configuration change maps to editFieldConfiguration with the changed
+          # property nested under its `byType` sub-hash (e.g. { gauge: { max: 5.0 } }). VersionDiff
+          # stamps `by_type` (the sub-hash key) and `parent_id` (the data field id). Without a
+          # by_type key we cannot address the typed input -> unsupported (never guessed).
+          def field_config_command(change)
+            return unsupported!(change) unless change.op == :changed
+
+            field_id = change.parent_id || change.id
+            by_type  = change.by_type
+            return unsupported!(change) if field_id.nil? || by_type.nil? || change.attribute.nil?
+
+            body = { by_type => { change.attribute.to_sym => change.after } }
+            build(:editFieldConfiguration, data_field_id: ref(field_id), byType: body)
+          end
+
+          # --- gauge stops ---------------------------------------------------
+
+          # Gauge stops address the parent gauge field id (parent_id). Add needs threshold+color
+          # (carried on change.after); edit/remove need the stop id (change.id).
+          def gauge_stop_command(change)
+            field_id = change.parent_id
+            return unsupported!(change) if field_id.nil?
+
+            field_ref = ref(field_id)
+            case change.op
+            when :added   then add_gauge_stop(change, field_ref)
+            when :removed then build(:removeGaugeFieldStop, data_field_id: field_ref, stop_id: change.id)
+            when :changed then edit_gauge_stop(change, field_ref)
+            else unsupported!(change)
+            end
+          end
+
+          def add_gauge_stop(change, field_id)
+            spec = change.after
+            return unsupported!(change) unless spec.is_a?(Hash)
+
+            build(:addGaugeFieldStop, data_field_id: field_id, threshold: spec[:threshold], color: spec[:color])
+          end
+
+          def edit_gauge_stop(change, field_id)
+            case change.attribute
+            when 'threshold' then build(:editGaugeFieldStop, data_field_id: field_id, stop_id: change.id, threshold: change.after)
+            when 'color'     then build(:editGaugeFieldStop, data_field_id: field_id, stop_id: change.id, color: change.after)
+            else unsupported!(change)
+            end
+          end
+
+          # --- option --------------------------------------------------------
+
+          def option_command(change)
+            field_id = change.parent_id
+            return unsupported!(change) if field_id.nil?
+
+            field_ref = ref(field_id)
+            case change.op
+            when :added   then build(:addSelectFieldOption, data_field_id: field_ref, label: change.label)
+            when :removed then build(:removeSelectFieldOption, data_field_id: field_ref, option_id: change.id)
+            when :changed then edit_option(change, field_ref)
+            else unsupported!(change)
+            end
+          end
+
+          def edit_option(change, field_id)
+            case change.attribute
+            when 'label'  then build(:editSelectFieldOption, data_field_id: field_id, option_id: change.id, label: change.after)
+            when 'weight' then build(:editSelectFieldOption, data_field_id: field_id, option_id: change.id, weight: change.after)
+            else unsupported!(change)
+            end
+          end
+
+          # --- helpers -------------------------------------------------------
+
+          def build(command_key, **kwargs)
+            Ecoportal::API::GraphQL::Input::WorkflowCommand.build(command_key, **kwargs)
+          end
+
+          # Ask the resolver for the target id of `key` (a heading / stage name). Returns nil when
+          # there is no resolver or it cannot resolve — callers treat nil as "unsupported".
+          def resolve(kind, key)
+            return nil if key.nil? || @resolver.nil?
+
+            @resolver.resolve(kind, key)
+          end
+
+          # Normalise a command_for result (nil | Hash | Array<Hash>) into a flat list of hashes.
+          # A built command is a Hash, so we must NOT use Kernel#Array (it would splat a Hash into
+          # key/value pairs).
+          def wrap(result)
+            case result
+            when nil   then []
+            when Array then result.compact
+            else [result]
+            end
+          end
+
+          # Record an unmappable change and return nil (filtered out of the command list).
+          def unsupported!(change)
+            @unsupported << change
+            nil
+          end
+        end
+      end
+    end
+  end
+end