ecoportal-api-graphql 1.3.9 → 1.3.11

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/fragment/location_draft.rb

@@ -1,53 +1,53 @@
-module Ecoportal
-  module API
-    class GraphQL
-      class Fragment
-        fragment :LocationDraft, <<~GRAPHQL
-          fragment LocationDraft on Draft {
-            id
-            name
-            notes
-            committed
-            createdAt { dateTime }
-            ok
-            conflictingIds
-            results {
-              ok
-              command {
-                id
-                state
-                __typename
-                ... on LocationInsertCommand    {
-                  nodeId name parentId insertBefore classificationIds
-                }
-                ... on LocationUpdateCommand    {
-                  nodeId newId
-                  newName: name
-                  newClassificationIds: classificationIds
-                }
-                ... on LocationArchiveCommand   { nodeId }
-                ... on LocationUnarchiveCommand { nodeId }
-                ... on LocationMoveCommand      { nodeId parentId insertBefore }
-                ... on LocationReorderCommand   { parentId orderedIds }
-              }
-              error {
-                message
-                conflictingIds
-                validationErrors {
-                  property
-                  error
-                  message
-                }
-              }
-            }
-            commands {
-              id
-              state
-              __typename
-            }
-          }
-        GRAPHQL
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        fragment :LocationDraft, <<~GRAPHQL
+          fragment LocationDraft on Draft {
+            id
+            name
+            notes
+            committed
+            createdAt
+            ok
+            conflictingIds
+            results {
+              ok
+              command {
+                id
+                state
+                __typename
+                ... on LocationInsertCommand    {
+                  nodeId name parentId insertBefore classificationIds
+                }
+                ... on LocationUpdateCommand    {
+                  nodeId newId
+                  newName: name
+                  newClassificationIds: classificationIds
+                }
+                ... on LocationArchiveCommand   { nodeId }
+                ... on LocationUnarchiveCommand { nodeId }
+                ... on LocationMoveCommand      { nodeId parentId insertBefore }
+                ... on LocationReorderCommand   { parentId orderedIds }
+              }
+              error {
+                message
+                conflictingIds
+                validationErrors {
+                  property
+                  error
+                  message
+                }
+              }
+            }
+            commands {
+              id
+              state
+              __typename
+            }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/fragment/pages/common_page_union.rb

@@ -119,6 +119,7 @@ module Ecoportal
               __typename
               id                @skip(if: $only_content)
               label
+              genomeSignature   @skip(if: $only_content)
               deindex           @include(if: $content)
               linkedFieldConfig @skip(if: $only_content) {
                 crossReferenceId

data/lib/ecoportal/api/graphql/input/workflow_command/add_field.rb

@@ -1,18 +1,27 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Input
-        class WorkflowCommand
-          module AddField
-            SCHEMA_VERSION = '20260605'.freeze
-            VALID_KEYS = %i[placeholderId fieldType label stageId sectionId column].freeze
-
-            def self.build(**kwargs)
-              kwargs.slice(*VALID_KEYS).compact
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class WorkflowCommand
+          module AddField
+            SCHEMA_VERSION = '20260605'.freeze
+            # VERIFIED against the live schema dump (WorkflowAddFieldInput, 20260605): the create
+            # command accepts ONLY these keys. There is NO `description` and NO `required` field on
+            # WorkflowAddFieldInput. `description` is instead a top-level key of
+            # WorkflowEditFieldConfigurationInput, so a field's description is persisted via a
+            # follow-up editFieldConfiguration command (see Builder::TemplateBuilder /
+            # Diff::CommandSynthesizer). `required` has NO input key anywhere in the schema (not on
+            # AddField, not on editFieldConfiguration top-level or any byType sub-input) and so
+            # cannot be persisted through the workflow command bus at all — callers must treat it as
+            # a read-only/unsupported attribute. Do NOT add these keys here (the server rejects them).
+            VALID_KEYS = %i[placeholderId fieldType label stageId sectionId column].freeze
+
+            def self.build(**kwargs)
+              kwargs.slice(*VALID_KEYS).compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/mutation/action/archive.rb

@@ -29,7 +29,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__Action
+                  spread :Action
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/action/create.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__Action
+                  spread :Action
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/action/update.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__Action
+                  spread :Action
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/contractor_entity/create.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__ContractorEntity
+                  spread :ContractorEntity
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/contractor_entity/destroy.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__ContractorEntity
+                  spread :ContractorEntity
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/contractor_entity/update.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__ContractorEntity
+                  spread :ContractorEntity
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/kickstand/fail_workflow.rb

@@ -27,7 +27,7 @@ module Ecoportal
 
             def default_payload_block
               proc {
-                item { id name status failedAt }
+                item { id name status failedAt { dateTime timeZone } }
                 errors { details fullMessages }
               }
             end

data/lib/ecoportal/api/graphql/mutation/kickstand/start_workflow.rb

@@ -27,7 +27,7 @@ module Ecoportal
 
             def default_payload_block
               proc {
-                item { id name status startedAt }
+                item { id name status startedAt { dateTime timeZone } }
                 errors { details fullMessages }
               }
             end

data/lib/ecoportal/api/graphql/mutation/kickstand/stop_workflow.rb

@@ -27,7 +27,7 @@ module Ecoportal
 
             def default_payload_block
               proc {
-                item { id name status stoppedAt }
+                item { id name status stoppedAt { dateTime timeZone } }
                 errors { details fullMessages }
               }
             end