ecoportal-api-graphql 1.3.5 → 1.3.17

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

@@ -0,0 +1,332 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # Self-version diff: two snapshots of the SAME page/template (same Mongo ids).
+        #
+        # Because the object keeps its ids across versions, pairing is EXACT (match by id) — no
+        # equivalence matching needed. This is the "what did this ticket change to the UAT template"
+        # tool, and the basis of a portable changelog ("commit") that — once id-translated through a
+        # pairing map — can be replayed onto PROD. Cross-object diff (UAT<->PROD, page<->template)
+        # is a different, harder problem handled by the pairing engine (not here).
+        #
+        # Operates on the raw page/template doc (the JSON the gem returns for a page/template), so it
+        # is a shared, session-less capability usable by admin/troubleshooting/integration/QA alike.
+        #
+        #   diff = Diff::VersionDiff.new(before_doc, after_doc)
+        #   diff.changes          # => [Change, ...]
+        #   diff.summary          # => { added:, removed:, changed:, moved:, total: }
+        #   diff.changelog        # => ["~ field 'Severity' ...", ...]
+        #
+        # MODALITIES — pass a `Diff::Strategy` to select a scope / move-sensitivity. The default
+        # strategy (id-paired, structural, move-aware, changelog) reproduces the pre-Phase-4 behaviour
+        # exactly, so `VersionDiff.new(before, after).changes` is unchanged. A narrower scope
+        # (`:config_only`, `:data_migration`) or a move-insensitive strategy filters the SAME computed
+        # change-set — the pairing is still by-id here (`VersionDiff` is the `:id` pairing front-end).
+        # Cross-object pairings (:genome/:type_label/:assisted) are handled by `CrossObjectDiff`.
+        class VersionDiff
+          # Typed field-configuration properties that this diff EMITS, keyed by the field's
+          # `__typename`. Each entry maps a `byType` input key (the sub-hash the schema's
+          # `editFieldConfiguration.byType` accepts) to the list of doc property names that make up
+          # that sub-hash. Only pairs where the READ property name matches the WRITE (byType) input
+          # key EXACTLY are listed here — this diff never fabricates a config change it cannot map
+          # back to a real command input.
+          #
+          # Deliberately conservative: e.g. PlainText carries `multiline` in the read model but the
+          # `plainText` byType input has no `multiline` key (it exposes `maxLength`), so PlainText
+          # config is NOT emitted here (it would be unmappable). Likewise `required` has no
+          # editFieldConfiguration key at all, so a `required` flip is not a config change we emit.
+          BYTYPE_CONFIG = {
+            'Gauge'  => { gauge:  %w[max] },
+            'Select' => { select: %w[dataType multiple flat other otherDesc] },
+            'Date'   => { date:   %w[showTime pastOnly todayButton] }
+          }.freeze
+
+          def initialize(before_doc, after_doc, strategy: Strategy.default)
+            @before   = before_doc || {}
+            @after    = after_doc  || {}
+            @strategy = strategy || Strategy.default
+          end
+
+          # The change-set, filtered by the strategy's scope + move-sensitivity. The full set is
+          # computed once (`all_changes`); the strategy decides what survives. The default strategy
+          # keeps everything (the historical behaviour).
+          def changes
+            @changes ||= @strategy.filter(all_changes)
+          end
+
+          def summary
+            by_op = changes.group_by(&:op)
+            {
+              added:   by_op.fetch(:added, []).size,
+              removed: by_op.fetch(:removed, []).size,
+              changed: by_op.fetch(:changed, []).size,
+              moved:   by_op.fetch(:moved, []).size,
+              total:   changes.size
+            }
+          end
+
+          def changelog
+            changes.map(&:description)
+          end
+
+          def to_h
+            { summary: summary, changes: changes.map(&:to_h) }
+          end
+
+          private
+
+          # The complete id-paired change-set (all kinds, all ops) before any strategy filtering.
+          def all_changes
+            stage_changes + section_changes + field_changes + option_changes +
+              field_config_changes + gauge_stop_changes
+          end
+
+          # Generic set-diff over an index {id => info}. Emits added/removed (label/path pulled from
+          # info via the given procs) and delegates matched-id comparison to the block.
+          #
+          # `parent:` (optional) is a proc mapping an entry's info to the id of its OWNING node — the
+          # section id for a field, the stage id for a section. Recorded on ADDED changes as
+          # `parent_id` so the synthesiser can wire the structural back-ref (addField.sectionId /
+          # addStageSection.stageId), threading through a placeholder when the parent is created in
+          # the same batch. nil (default) means no parent id is known/recorded — the historical
+          # behaviour, unchanged.
+          def diff_index(kind, before_idx, after_idx, label:, path:, parent: nil, owner: nil, &compare)
+            procs   = { label: label, path: path, parent: parent, owner: owner }
+            removed = (before_idx.keys - after_idx.keys).map { |id| removed_change(kind, id, before_idx[id], procs) }
+            added   = (after_idx.keys - before_idx.keys).map { |id| added_change(kind, id, after_idx[id], procs) }
+            matched = (before_idx.keys & after_idx.keys).flat_map { |id| Array(compare.call(id, before_idx[id], after_idx[id])) }
+            removed + added + matched
+          end
+
+          def removed_change(kind, id, info, procs)
+            Change.new(op: :removed, kind: kind, id: id, label: procs[:label].call(info), path: procs[:path].call(info))
+          end
+
+          def added_change(kind, id, info, procs)
+            Change.new(op: :added, kind: kind, id: id, label: procs[:label].call(info), path: procs[:path].call(info),
+                       parent_id: procs[:parent]&.call(info), owner_id: procs[:owner]&.call(info))
+          end
+
+          def stage_changes
+            diff_index(:stage, index_stages(@before), index_stages(@after),
+                       label: ->(s) { s['name'] }, path: ->(s) { s['name'] }) do |id, b, a|
+              cmp = []
+              cmp << changed(:stage, id, a['name'], a['name'], 'name', b['name'], a['name']) if b['name'] != a['name']
+              cmp << moved(:stage, id, a['name'], 'ordering', b['ordering'], a['ordering']) if b['ordering'] != a['ordering']
+              cmp
+            end
+          end
+
+          def section_changes
+            diff_index(:section, index_sections(@before), index_sections(@after),
+                       label: ->(s) { s[:heading] }, path: ->(s) { s[:path] },
+                       parent: ->(s) { s[:stage_id] }) do |id, b, a|
+              cmp = []
+              cmp << changed(:section, id, a[:heading], a[:path], 'heading', b[:heading], a[:heading]) if b[:heading] != a[:heading]
+              cmp << moved(:section, id, a[:heading], 'stage', b[:stage], a[:stage]) if b[:stage] != a[:stage]
+              cmp
+            end
+          end
+
+          def field_changes
+            diff_index(:field, index_fields(@before), index_fields(@after),
+                       label: ->(f) { f[:label] }, path: ->(f) { f[:path] },
+                       parent: ->(f) { f[:section_id] }, owner: ->(f) { f[:stage_id] }, &method(:compare_field))
+          end
+
+          def compare_field(id, before, after)
+            cmp = []
+            cmp << changed(:field, id, after[:label], after[:path], 'label', before[:label], after[:label]) if before[:label] != after[:label]
+            cmp << changed(:field, id, after[:label], after[:path], 'type', before[:type], after[:type]) if before[:type] != after[:type]
+            cmp << moved(:field, id, after[:label], 'section', before[:section], after[:section]) if before[:section] != after[:section]
+            cmp
+          end
+
+          def option_changes
+            bf = index_fields(@before)
+            af = index_fields(@after)
+            (bf.keys & af.keys).flat_map do |fid|
+              options_diff(fid, af[fid][:path], bf[fid][:field], af[fid][:field])
+            end
+          end
+
+          def options_diff(field_id, path, before_field, after_field)
+            diff_index(:option, index_options(before_field), index_options(after_field),
+                       label: ->(o) { o[:label] }, path: ->(_o) { path }) do |k, b, a|
+              cmp = []
+              cmp << changed(:option, k, a[:label], path, 'label', b[:label], a[:label], field_id) if b[:label] != a[:label]
+              cmp << changed(:option, k, a[:label], path, 'weight', b[:weight], a[:weight], field_id) if b[:weight] != a[:weight]
+              cmp
+            end.each { |c| c.parent_id ||= field_id }
+          end
+
+          # --- typed field configuration (byType) ---------------------------
+
+          # Per-type field-configuration changes (the `byType` body of editFieldConfiguration).
+          # Matched by retained field id (self-version). For each field type in BYTYPE_CONFIG, emit
+          # a `:field_config` change per changed property, carrying the byType key so the synthesiser
+          # can nest it under the right sub-hash. Properties absent from BYTYPE_CONFIG are ignored
+          # here (unmappable → never fabricated).
+          def field_config_changes
+            bf = index_fields(@before)
+            af = index_fields(@after)
+            (bf.keys & af.keys).flat_map do |fid|
+              config_diff_for_field(fid, bf[fid], af[fid])
+            end
+          end
+
+          def config_diff_for_field(field_id, before_info, after_info)
+            type = after_info[:type]
+            return [] if before_info[:type] != type # a type change is handled/blocked elsewhere
+
+            (BYTYPE_CONFIG[type] || {}).flat_map do |by_type, props|
+              props.filter_map do |prop|
+                bv = before_info[:field][prop]
+                av = after_info[:field][prop]
+                next if bv == av
+
+                config_change(field_id, after_info, by_type, prop, bv, av)
+              end
+            end
+          end
+
+          def config_change(field_id, after_info, by_type, prop, before, after) # rubocop:disable Metrics/ParameterLists
+            Change.new(op: :changed, kind: :field_config, id: field_id, label: after_info[:label],
+                       path: after_info[:path], attribute: prop, before: before, after: after,
+                       parent_id: field_id, by_type: by_type)
+          end
+
+          # --- gauge stops ---------------------------------------------------
+
+          # Gauge fields carry an ordered list of `stops` ({ id, threshold, color }). Diff them per
+          # gauge field, matched by retained stop id (self-version). Added / removed / changed
+          # (threshold or color). parent_id = the gauge field id (the stop commands address it).
+          def gauge_stop_changes
+            bf = index_fields(@before)
+            af = index_fields(@after)
+            (bf.keys & af.keys).flat_map do |fid|
+              next [] unless af[fid][:type] == 'Gauge' && bf[fid][:type] == 'Gauge'
+
+              stops_diff(fid, af[fid][:path], bf[fid][:field], af[fid][:field])
+            end
+          end
+
+          # Explicit add/remove/change diff (NOT the generic diff_index): an ADDED stop must carry
+          # its full spec (threshold + color) on the Change so addGaugeFieldStop can be built without
+          # re-reading the doc.
+          def stops_diff(field_id, path, before_field, after_field)
+            before_idx = index_stops(before_field)
+            after_idx  = index_stops(after_field)
+
+            removed = (before_idx.keys - after_idx.keys).map do |sid|
+              Change.new(op: :removed, kind: :gauge_stop, id: sid, label: before_idx[sid][:label],
+                         path: path, parent_id: field_id)
+            end
+            added = (after_idx.keys - before_idx.keys).map do |sid|
+              s = after_idx[sid]
+              Change.new(op: :added, kind: :gauge_stop, id: sid, label: s[:label], path: path,
+                         parent_id: field_id, after: { threshold: s[:threshold], color: s[:color] })
+            end
+            changed = (before_idx.keys & after_idx.keys).flat_map do |sid|
+              stop_attr_changes(field_id, sid, path, before_idx[sid], after_idx[sid])
+            end
+            removed + added + changed
+          end
+
+          def stop_attr_changes(field_id, stop_id, path, before, after)
+            cmp = []
+            cmp << stop_changed(field_id, stop_id, path, 'threshold', before[:threshold], after[:threshold]) if before[:threshold] != after[:threshold]
+            cmp << stop_changed(field_id, stop_id, path, 'color', before[:color], after[:color]) if before[:color] != after[:color]
+            cmp
+          end
+
+          def stop_changed(field_id, stop_id, path, attribute, before, after) # rubocop:disable Metrics/ParameterLists
+            Change.new(op: :changed, kind: :gauge_stop, id: stop_id, label: "#{attribute} #{after}".strip,
+                       path: path, attribute: attribute, before: before, after: after, parent_id: field_id)
+          end
+
+          # Stops keyed by id, carrying threshold + color (an ADD needs both to build the command).
+          def index_stops(field)
+            Array(field['stops']).each_with_object({}) do |s, h|
+              next unless s.is_a?(Hash) && s['id']
+
+              h[s['id']] = { threshold: s['threshold'], color: s['color'],
+                             label: "#{s['threshold']} #{s['color']}".strip }
+            end
+          end
+
+          # --- indexing helpers ---------------------------------------------
+
+          def index_stages(doc)
+            stages(doc).each_with_object({}) { |st, h| h[st['id']] = st if st['id'] }
+          end
+
+          def index_sections(doc)
+            out = {}
+            stages(doc).each do |st|
+              sections(st).each do |sec|
+                next unless sec['id']
+
+                out[sec['id']] = { heading: sec['heading'], stage: st['name'], stage_id: st['id'],
+                                   path: "#{st['name']} / #{sec['heading']}" }
+              end
+            end
+            out
+          end
+
+          def index_fields(doc)
+            out = {}
+            stages(doc).each do |st|
+              sections(st).each do |sec|
+                fields(sec).each do |f|
+                  next unless f['id']
+
+                  out[f['id']] = {
+                    field: f, label: f['label'], type: f['__typename'] || f['type'],
+                    section: sec['heading'], section_id: sec['id'], stage_id: st['id'],
+                    path: "#{st['name']} / #{sec['heading']} / #{f['label']}"
+                  }
+                end
+              end
+            end
+            out
+          end
+
+          # Options keyed by id when present, else by value (primary) / name (auxiliary) — the
+          # correct select-option identity (NOT genome).
+          def index_options(field)
+            Array(field['options']).each_with_object({}) do |o, h|
+              next unless o.is_a?(Hash)
+
+              key = o['id'] || o['value'] || o['label'] || o['name']
+              h[key] = { label: o['label'] || o['name'] || o['value'], weight: o['weight'] }
+            end
+          end
+
+          def stages(doc)
+            Array(doc['stages'])
+          end
+
+          def sections(stage)
+            Array(stage['sections'])
+          end
+
+          def fields(section)
+            Array(section['dataFields']) + Array(section['leftDataFields']) + Array(section['rightDataFields'])
+          end
+
+          def changed(kind, id, label, path, attribute, before, after, parent_id = nil) # rubocop:disable Metrics/ParameterLists
+            Change.new(op: :changed, kind: kind, id: id, label: label, path: path,
+                       attribute: attribute, before: before, after: after, parent_id: parent_id)
+          end
+
+          def moved(kind, id, label, attribute, before, after) # rubocop:disable Metrics/ParameterLists
+            Change.new(op: :moved, kind: kind, id: id, label: label,
+                       attribute: attribute, before: before, after: after)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Ecoportal
+  module API
+    class GraphQL
+      # Diff engines over the page/template model.
+      #
+      # `VersionDiff` handles the EASY, exact case — two snapshots of the SAME object (same ids),
+      # e.g. a UAT template at version N vs N+1 ("what did this ticket change"). The HARD case —
+      # pairing two DIFFERENT objects with different ids (UAT<->PROD, page<->template) — is an
+      # equivalence-matching problem handled by `Diff::Pairing` (multi-signal + learning ledger).
+      #
+      # `CommandSynthesizer` turns a change-set into an ordered WorkflowCommand batch (the replayable
+      # "commit"); `IdResolver` fills in move-target ids from a target doc; `Deploy` orchestrates
+      # diff -> commands -> apply, gating on the honest `unsupported` list.
+      #
+      # `Strategy` makes diffing a COMPOSABLE family (pairing x scope x move-sensitivity x intent);
+      # `CrossObjectDiff` is the cross-object front-end (pairs fields via `Pairing::Engine`, then
+      # emits the same `Change` output against the pairing map).
+      module Diff
+      end
+    end
+  end
+end
+
+require_relative 'diff/change'
+require_relative 'diff/strategy'
+require_relative 'diff/version_diff'
+require_relative 'diff/id_resolver'
+require_relative 'diff/command_synthesizer'
+require_relative 'diff/pairing/ledger'
+require_relative 'diff/pairing/candidate'
+require_relative 'diff/pairing/signals'
+require_relative 'diff/pairing/engine'
+require_relative 'diff/cross_object_diff'
+require_relative 'diff/deploy'

data/lib/ecoportal/api/graphql/error/locations_error/fetch_nested.rb

@@ -1,51 +1,51 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Error
-        class LocationsError < Logic::BaseModel
-          module FetchNested
-            def locations_error_doc
-              return unless locations_error?
-
-              if loc_err_conflicting_ids?
-                {
-                  conflictingIds: loc_err_conflicting_ids.doc
-                }
-              elsif validationErrors?
-                {
-                  validationErrors: validationErrors.doc
-                }
-              end
-            end
-
-            def locations_error?
-              return false if error.nil?
-
-              !error.empty?
-            end
-
-            def loc_err_conflicting_ids?
-              loc_err_conflicting_ids.any?
-            end
-
-            def validationErrors?
-              validationErrors.any?
-            end
-
-            def loc_err_conflicting_ids
-              return [] unless (err = error)
-
-              err.conflictingIds || []
-            end
-
-            def validationErrors
-              return [] unless (err = error)
-
-              err.validationErrors || []
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Error
+        class LocationsError < Logic::BaseModel
+          module FetchNested
+            def locations_error_doc
+              return unless locations_error?
+
+              if loc_err_conflicting_ids?
+                {
+                  conflictingIds: loc_err_conflicting_ids.doc
+                }
+              elsif validationErrors?
+                {
+                  validationErrors: validationErrors.doc
+                }
+              end
+            end
+
+            def locations_error?
+              return false if error.nil?
+
+              !error.empty?
+            end
+
+            def loc_err_conflicting_ids?
+              loc_err_conflicting_ids.any?
+            end
+
+            def validationErrors?
+              validationErrors.any?
+            end
+
+            def loc_err_conflicting_ids
+              return [] unless (err = error)
+
+              err.conflictingIds || []
+            end
+
+            def validationErrors
+              return [] unless (err = error)
+
+              err.validationErrors || []
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/error/locations_error.rb

@@ -1,28 +1,28 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Error
-        class LocationsError < Logic::BaseModel
-          read_only!
-
-          passthrough :type, :message
-          passarray :conflictingIds
-          embeds_many :validationErrors, klass: LocationsValidationError
-
-          def empty?
-            return false unless conflictingIds.empty?
-
-            validationErrors.empty?
-          end
-
-          def any?
-            !empty?
-          end
-        end
-      end
-    end
-  end
-end
-
-
-require_relative 'locations_error/fetch_nested'
+module Ecoportal
+  module API
+    class GraphQL
+      module Error
+        class LocationsError < Logic::BaseModel
+          read_only!
+
+          passthrough :type, :message
+          passarray :conflictingIds
+          embeds_many :validationErrors, klass: LocationsValidationError
+
+          def empty?
+            return false unless conflictingIds.empty?
+
+            validationErrors.empty?
+          end
+
+          def any?
+            !empty?
+          end
+        end
+      end
+    end
+  end
+end
+
+
+require_relative 'locations_error/fetch_nested'

data/lib/ecoportal/api/graphql/error/locations_validation_error.rb

@@ -1,20 +1,20 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Error
-        class LocationsValidationError < Logic::BaseModel
-          read_only!
-
-          passthrough :error, :message, :property
-
-          def empty?
-            return false unless error.nil?
-            return false unless message.nil?
-
-            property.nil?
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Error
+        class LocationsValidationError < Logic::BaseModel
+          read_only!
+
+          passthrough :error, :message, :property
+
+          def empty?
+            return false unless error.nil?
+            return false unless message.nil?
+
+            property.nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/error/validation_errors.rb

@@ -1,28 +1,28 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Error
-        class ValidationErrors < Logic::BaseModel
-          include Enumerable
-
-          passthrough :details
-          passarray :fullMessages
-
-          def empty?
-            count < 1
-          end
-
-          def any?
-            !empty?
-          end
-
-          def each(&block)
-            return to_enum(:each) unless block
-
-            fullMessages.each(&block)
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Error
+        class ValidationErrors < Logic::BaseModel
+          include Enumerable
+
+          passthrough :details
+          passarray :fullMessages
+
+          def empty?
+            count < 1
+          end
+
+          def any?
+            !empty?
+          end
+
+          def each(&block)
+            return to_enum(:each) unless block
+
+            fullMessages.each(&block)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,12 +1,12 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Error
-      end
-    end
-  end
-end
-
-require_relative 'error/locations_validation_error'
-require_relative 'error/validation_errors'
-require_relative 'error/locations_error'
+module Ecoportal
+  module API
+    class GraphQL
+      module Error
+      end
+    end
+  end
+end
+
+require_relative 'error/locations_validation_error'
+require_relative 'error/validation_errors'
+require_relative 'error/locations_error'