eco-helpers 3.2.14 → 3.2.22

data/lib/eco/api/usecases/graphql/compat/parity/harness.rb

@@ -0,0 +1,102 @@
+module Eco::API::UseCases::GraphQL::Compat
+  module Parity
+    # A/B parity harness for the ooze -> native GraphQL strangler-fig migration.
+    #
+    # Runs the SAME logical register-processing case through the two code paths —
+    # A: legacy (v2 / OozeRedirect shim), B: native GraphQL — and asserts that the
+    # observable outcome (KPI counters + per-page update payloads) is equivalent.
+    #
+    # The comparison logic (RunResult / Comparison) is PURE and offline-runnable.
+    # The harness itself is a thin orchestrator: you hand it two callables, each of
+    # which runs its side and returns a RunResult. In a live run each callable would
+    # execute the case in `-simulate` mode against the same test org, using a
+    # Recorder to capture what each side WOULD write (no data is mutated). Wiring the
+    # two live runs needs credentials + a test org; the structural machinery here is
+    # verified offline.
+    #
+    # == Usage (live)
+    #
+    #   harness = Parity::Harness.new(
+    #     legacy: -> { Parity::Harness.record('legacy') { |rec| run_legacy_case(rec) } },
+    #     native: -> { Parity::Harness.record('native') { |rec| run_native_case(rec) } }
+    #   )
+    #   comparison = harness.run
+    #   raise comparison.report unless comparison.equivalent?
+    #
+    # == Usage (offline / spec)
+    #
+    #   a = Parity::RunResult.new(label: 'legacy', kpis: {...}, updates: {...})
+    #   b = Parity::RunResult.new(label: 'native', kpis: {...}, updates: {...})
+    #   Parity::Harness.new(legacy: -> { a }, native: -> { b }).run.equivalent?
+    class Harness
+      # @param legacy [#call] returns the legacy-path RunResult.
+      # @param native [#call] returns the native-path RunResult.
+      def initialize(legacy:, native:)
+        @legacy = legacy
+        @native = native
+      end
+
+      # Execute both sides and compare. Returns a Parity::Comparison.
+      def run
+        a = @legacy.call
+        b = @native.call
+        assert_run_result!(a, 'legacy')
+        assert_run_result!(b, 'native')
+        a.compare_to(b)
+      end
+
+      # Capture the observable outcome of a case run into a RunResult.
+      #
+      # Yields a Recorder. The caller runs the case, feeding each page's would-be
+      # update payload to `recorder.record_update(page_id, payload)` (typically wired
+      # by stubbing the case's `update_page` to call `graphql.pages.get_body(page)`
+      # instead of persisting). After the run, pass the case's KPI hash to
+      # `recorder.kpis = case.kpis_hash` (or set counters individually).
+      #
+      # @param label [String] 'legacy' or 'native'.
+      # @yieldparam recorder [Recorder]
+      # @return [RunResult]
+      def self.record(label)
+        recorder = Recorder.new(label)
+        yield(recorder) if block_given?
+        recorder.to_run_result
+      end
+
+      private
+
+      def assert_run_result!(obj, side)
+        return if obj.is_a?(RunResult)
+
+        raise TypeError, "The #{side} callable must return a Parity::RunResult, got #{obj.class}"
+      end
+
+      # Collects a run's KPIs + per-page update payloads, then bakes a RunResult.
+      class Recorder
+        attr_accessor :kpis
+
+        def initialize(label)
+          @label   = label
+          @kpis    = {}
+          @updates = {}
+        end
+
+        # Record what a run WOULD send for `page_id`. Later ids for the same page
+        # overwrite (the last state wins — matching a real save of the final page).
+        def record_update(page_id, payload)
+          @updates[page_id.to_s] = payload
+          self
+        end
+
+        # Set a single canonical/native KPI counter by name.
+        def kpi(name, value)
+          @kpis[name.to_sym] = value
+          self
+        end
+
+        def to_run_result
+          RunResult.new(label: @label, kpis: @kpis, updates: @updates)
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/compat/parity/run_result.rb

@@ -0,0 +1,96 @@
+module Eco::API::UseCases::GraphQL::Compat
+  module Parity
+    # A normalised, comparable snapshot of ONE use-case run.
+    #
+    # The A/B parity harness reduces a run — whether it went through the legacy
+    # (v2 / OozeRedirect) path or the native GraphQL path — to just its OBSERVABLE
+    # outcome:
+    #   * `kpis`    — the KPI counter hash (search/retrieved/updated/created/… )
+    #   * `updates` — the per-page update payload the run WOULD send, keyed by page id
+    #
+    # Two runs are "equivalent" when, after normalisation, both are identical. This
+    # is the unit the strangler-fig migration is gated on: flip a case name only once
+    # its native RunResult matches the legacy RunResult over the same input.
+    #
+    # Everything here is PURE (no session, no network) so equivalence can be asserted
+    # offline in specs; the live capture step (feeding real runs in) is the only part
+    # that needs credentials.
+    class RunResult
+      attr_reader :label, :kpis, :updates
+
+      # @param label   [String] human tag for this side ('legacy' / 'native').
+      # @param kpis     [Hash] KPI counters. Keys are symbolised; values coerced to Integer.
+      # @param updates  [Hash{String=>Object}] page_id => update payload (any Hash-ish).
+      def initialize(label:, kpis: {}, updates: {})
+        @label   = label.to_s
+        @kpis    = normalize_kpis(kpis)
+        @updates = normalize_updates(updates)
+      end
+
+      # The set of page ids this run acted on.
+      def page_ids
+        updates.keys
+      end
+
+      # Compare against another RunResult, returning a Comparison value object.
+      def compare_to(other)
+        Comparison.new(self, other)
+      end
+
+      # Convenience: are the two runs equivalent?
+      def equivalent_to?(other)
+        compare_to(other).equivalent?
+      end
+
+      # Merge/normalise into a plain hash (handy for golden-file capture).
+      def to_h
+        { label: label, kpis: kpis, updates: updates }
+      end
+
+      # KPI names differ between the legacy and native cases (e.g. `updated_oozes`
+      # vs `updated_pages`). We compare on a CANONICAL subset of counters that both
+      # sides expose the same way, mapping each side's names onto the canon.
+      CANON_KPI_ALIASES = {
+        search:     %i[total_search_oozes total_search_pages search],
+        duplicated: %i[dupped_search_oozes dupped_search_pages duplicated],
+        retrieved:  %i[retrieved_oozes retrieved_pages retrieved],
+        updated:    %i[updated_oozes updated_pages updated],
+        created:    %i[created_oozes created_pages created],
+        skipped:    %i[skipped_pages skipped],
+        failed:     %i[failed_update_oozes failed_pages failed]
+      }.freeze
+
+      private
+
+      def normalize_kpis(raw)
+        source = raw.each_with_object({}) do |(k, v), out|
+          out[k.to_sym] = v
+        end
+
+        CANON_KPI_ALIASES.each_with_object({}) do |(canon, aliases), out|
+          key = aliases.find {|a| source.key?(a)}
+          out[canon] = key ? source[key].to_i : 0
+        end
+      end
+
+      # Normalise each update payload so a superficial key-order / string-vs-symbol
+      # difference between the two paths does not read as a real divergence.
+      def normalize_updates(raw)
+        raw.each_with_object({}) do |(id, payload), out|
+          out[id.to_s] = deep_normalize(payload)
+        end
+      end
+
+      def deep_normalize(value)
+        case value
+        when Hash
+          value.map {|k, v| [k.to_s, deep_normalize(v)]}.sort_by(&:first).to_h
+        when Array
+          value.map {|v| deep_normalize(v)}
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/compat.rb

@@ -0,0 +1,11 @@
+module Eco::API::UseCases::GraphQL
+  module Compat
+    module Parity
+    end
+  end
+end
+
+require_relative 'compat/ooze_redirect'
+require_relative 'compat/parity/run_result'
+require_relative 'compat/parity/comparison'
+require_relative 'compat/parity/harness'

data/lib/eco/api/usecases/graphql/helpers/CLAUDE.md

@@ -0,0 +1,79 @@
+# usecases/graphql/helpers
+
+Mixin modules providing domain-specific helper methods for GraphQL use cases.
+All modules are ultimately included via `Helpers::Base` into `GraphQL::Base`.
+
+---
+
+## Include chain
+
+```
+GraphQL::Base
+    includes Helpers::Base
+        includes CaseEnv        → session, options, config, simulate?, log, ErrorHandling
+        includes GraphQLEnv     → graphql (lazy, memoized)
+    includes Helpers (loader)
+        includes Helpers::Location      → location tree helpers
+        includes Helpers::Contractors   → contractor entity helpers
+```
+
+---
+
+## Helpers::Base (`helpers/base.rb`)
+
+Core environment — included in every GraphQL use case.
+
+| Method | Source | Description |
+|--------|--------|-------------|
+| `session` | `CaseEnv` | Current `Eco::API::Session` |
+| `options` | `CaseEnv` | Options hash from CLI/runner |
+| `config` | `CaseEnv` | `session.config` shortcut |
+| `simulate?` | `CaseEnv` | `options[:simulate] \|\| options[:dry_run]` |
+| `log(level)` | `CaseEnv` | Logger proxy |
+| `graphql` | `GraphQLEnv` | Lazy-loaded `Ecoportal::API::GraphQL` instance |
+| `backup(data, type:)` | `Helpers::Base` | Save JSON to requests folder |
+| `exit_error(msg)` | `Helpers::Base` | Log error and `exit(1)` |
+
+---
+
+## Helpers::Location (`helpers/location/`)
+
+Location tree access, tag remapping, classification parsing.
+
+- `helpers/location/base.rb` — `Location::Base` mixin
+- `helpers/location/base/tree_tracking.rb` — track tree mutations
+- `helpers/location/base/classifications_parser.rb` — parse location classifications
+- `helpers/location/tags_remap/` — remapping tags across location changes
+- `helpers/location/command/` — apply/diff location structure commands
+
+---
+
+## Helpers::Contractors (`helpers/contractors/`)
+
+Contractor entity loading helpers.
+
+- `helpers/contractors/base.rb` — base contractor helpers
+- `helpers/contractors/base/load.rb` — batch load contractor entities
+
+---
+
+## Adding a new helper
+
+1. Create `helpers/my_domain/base.rb`:
+   ```ruby
+   module Eco::API::UseCases::GraphQL::Helpers
+     module MyDomain
+       module Base
+         private
+         def my_helper_method
+           graphql.myDomainQuery(...)
+         end
+       end
+     end
+   end
+   ```
+2. Create `helpers/my_domain.rb` as a loader that includes `Base`
+3. Add `require_relative 'my_domain'` to `helpers.rb`
+
+The helper is then available in all cases that include `Helpers::Base` (i.e., all
+subclasses of `GraphQL::Base` including `PageCase` and `OrgPageCase`).

data/lib/eco/api/usecases/graphql/helpers/location/command/end_points/optimizations.rb

@@ -29,7 +29,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
             messages
           }
           draft { # rubocop:disable Style/BlockDelimiters
-            ___Ecoportal__API__GraphQL__Fragment__LocationDraft
+            spread :LocationDraft
           }
         }
       end
@@ -44,7 +44,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
             messages
           }
           draft { # rubocop:disable Style/BlockDelimiters
-            ___Ecoportal__API__GraphQL__Fragment__LocationDraft
+            spread :LocationDraft
           }
         }
       end
@@ -54,7 +54,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
           clientMutationId
           ok
           error { # rubocop:disable Style/BlockDelimiters
-            ___Ecoportal__API__GraphQL__Fragment__LocationsError
+            spread :LocationsError
           }
           errors { # rubocop:disable Style/BlockDelimiters
             details
@@ -69,7 +69,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
               __typename
             }
             error { # rubocop:disable Style/BlockDelimiters
-              ___Ecoportal__API__GraphQL__Fragment__LocationsError
+              spread :LocationsError
             }
           }
         }

data/lib/eco/api/usecases/graphql/helpers/pages/copying.rb

@@ -0,0 +1,71 @@
+module Eco::API::UseCases::GraphQL::Helpers
+  module Pages
+    # Native GraphQL re-expression of OozeSamples::HelpersMigration::Copying.
+    #
+    # Provides the "pair source fields to destination fields and copy their
+    # content across" flow used by the native migration case. Pairing is delegated
+    # to `TypedFieldsPairing`; the per-field content copy (`copy_field_content`)
+    # dispatches on the GraphQL DataField TYPE STRING (PlainText/Select/Date/...),
+    # mirroring how OozeHandlers#merge_values ports the v2 type-class dispatch.
+    #
+    # Only the generic-typed-pairing flow is ported (the v2 regex/JSON hooked-field
+    # mapping — `copy_hooked_fields` / `with_src_dst_field_pair` — is a later
+    # increment and is intentionally omitted here).
+    module Copying
+      include Eco::Language::AuxiliarLogger
+      include Eco::API::UseCases::GraphQL::Helpers::Pages::Shortcuts
+
+      def session
+        defined?(super) ? super : @session
+      end
+
+      # Pair the same-type/same-label fields of `src` and `dst`, and copy the
+      # content of each pair from source to destination.
+      #
+      # @param src [Object] the source page model.
+      # @param dst [Object] the destination (draft) page model.
+      # @param src_excluded [Array] source fields to exclude from pairing.
+      # @param dst_excluded [Array] destination fields to exclude from pairing.
+      # @param exclude_ximport [Boolean] skip ximport-marked fields.
+      # @yield [src_fld, dst_fld, pairing] optional post-copy callback per pair.
+      # @return [TypedFieldsPairing] the tracker (unpaired / multi-pair inspection).
+      def copy_generic_paired_fields(src, dst, src_excluded: [], dst_excluded: [], exclude_ximport: false)
+        TypedFieldsPairing.new(
+          src,
+          dst,
+          src_excluded:    src_excluded,
+          dst_excluded:    dst_excluded,
+          exclude_ximport: exclude_ximport
+        ).tap do |pairing|
+          pairing.each_pair do |src_fld, dst_fld|
+            copy_field_content(src_fld, dst_fld)
+            yield(src_fld, dst_fld, pairing) if block_given?
+          end
+        end
+      end
+
+      # Copy the content of `src` into `dst`, dispatching on the GraphQL DataField
+      # TYPE STRING. `src` and `dst` are guaranteed to be the same type by the
+      # pairing. Types with no meaningful/copyable content (or whose native setter
+      # is not yet supported) are left untouched.
+      #
+      # @param src [#type] the source data field.
+      # @param dst [#type] the destination data field.
+      # @return [Object] result of the per-type copy (or a "won't copy" marker).
+      def copy_field_content(src, dst)
+        case src.type.to_s
+        when 'PlainText', 'Number', 'Date', 'Gauge'
+          dst.value = src.value
+        when 'RichText'
+          dst.content = src.content
+        when 'Select'
+          dst.select_option(*src.selected_options.map { |opt| opt['id'] })
+        when 'CrossReference'
+          dst.page_ids = src.page_ids
+        else
+          "won't copy"
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/pages/creatable.rb

@@ -0,0 +1,78 @@
+module Eco::API::UseCases::GraphQL::Helpers
+  module Pages
+    # Native GraphQL re-expression of OozeSamples::Helpers::Creatable.
+    #
+    # Provides the "create a new entry (page) from a template" flow used by
+    # register-processing use cases. Mirrors the v2 Creatable structure
+    # (creating_new_page -> drafting_entry -> create_entry -> create_ooze) but
+    # talks to the native GraphQL stack (`graphql.pages.get_new` / `graphql.pages.create`)
+    # and respects `simulate?` for dry-run feedback.
+    #
+    # Included via the base-type guard: it can only be mixed into the native
+    # register case (Samples::Pages::Register::Base), which supplies the
+    # `create_ooze` hook + KPI counters it drives.
+    module Creatable
+      module InstanceMethods
+        private
+
+        # Draft a page from `template_id`, let the caller fill it, then persist it.
+        # @param draft_reference [String] human-readable label for logs.
+        # @param template_id [String] the template to build the draft from.
+        # @yield [draft] the built (still unsaved) draft page to mutate.
+        # @return [String, nil] the created page id, or nil on dry-run / failure.
+        def creating_new_page(draft_reference = 'new entry', template_id:)
+          page_id = nil
+          drafting_entry(template_id) do |draft|
+            yield(draft) if block_given?
+
+            if (page_id = create_entry(draft, reference: draft_reference))
+              log(:info) { "Page '#{page_id}' created successfully -- #{draft_reference}" }
+            elsif simulate?
+              log(:info) { "Simulated launch for #{draft_reference}" }
+            end
+          end
+          page_id
+        end
+
+        # @return [Object] a draft page of `template_id` (still not saved).
+        def drafting_entry(template_id)
+          raise ArgumentError, 'Expecting block, but not given' unless block_given?
+
+          draft = graphql.pages.get_new(template_id)
+          yield(draft)
+        end
+
+        # Does the actual creation of the entry (wrapped so a per-item error does
+        # not abort the whole run).
+        # @return [String, nil] the created page id, or nil.
+        def create_entry(draft, reference: "new entry from #{draft&.template_id}")
+          with_rescue(reference) do
+            if (result = create_ooze(draft, template_id: draft.template_id))
+              return result.page_id
+            end
+          end
+        end
+      end
+
+      class << self
+        def included(base)
+          super
+
+          validate_base_type!(base)
+          base.include(InstanceMethods)
+        end
+
+        def validate_base_type!(base)
+          return super if defined?(super)
+
+          register_base = Eco::API::UseCases::GraphQL::Samples::Pages::Register::Base
+          msg  = "#{self} can only be included in #{register_base}"
+          msg << "\nCan't be included in #{base}"
+          raise LoadError, msg unless base <= register_base
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/pages/filters.rb

@@ -0,0 +1,114 @@
+# rubocop:disable Lint/SymbolConversion, Style/QuotedSymbols
+module Eco::API::UseCases::GraphQL::Helpers
+  module Pages
+    # Search-filter + time-math helpers, ported from OozeSamples::Helpers::Filters.
+    #
+    # The time/date/tag builders are pure and ported verbatim. #field_key_name's field branch
+    # is re-expressed with duck-typing (was a `V2::Page::Component` case) — see the note there.
+    # A `weekday` helper is added because the original relied on one defined outside Filters
+    # (undefined in lib/), which made the sunday/monday chain latent-broken.
+    module Filters
+      FILTER_TIME_FORMAT = '%Y-%m-%dT%H:%M:%SZ'.freeze
+
+      def tags_filter(tags, any: true, negate: false)
+        tags = [tags].flatten.compact
+        return nil if tags.empty?
+        key, name = field_key_name(:tags)
+        {
+          "tags":   tags,
+          "mode":   any ? "any" : "all",
+          "negate": negate,
+          "key":    key,
+          "name":   name,
+          "type":   "tag_filter"
+        }
+      end
+
+      def date_range_filter(from: nil, to: nil, key: :updated_at)
+        return nil unless from || to
+        key, name = field_key_name(key)
+        {
+          "relstart":  "today",
+          "time_zone": "Pacific/Auckland",
+          "relative":  false,
+          "key":       key,
+          "name":      name,
+          "type":      "date_filter"
+        }.tap do |out|
+          out.merge!("lbound": to_date_filter(from)) if from
+          out.merge!("ubound": to_date_filter(to)) if to
+        end
+      end
+
+      def to_date_filter(date)
+        daystart(date).utc.strftime(FILTER_TIME_FORMAT)
+      end
+
+      def set_time(date, hour, min, sec)
+        Time.new(date.year, date.month, date.day, hour, min, sec)
+      end
+
+      def weeks(num)
+        num * days(7)
+      end
+
+      def days(num)
+        num * 60 * 60 * 24
+      end
+
+      def today
+        Date.today.to_time
+      end
+
+      # 0 = Sunday .. 6 = Saturday (Date#wday). Added: the original relied on a `weekday`
+      # helper defined outside Filters (not present in lib/), leaving the chain below broken.
+      def weekday(date)
+        (date.respond_to?(:to_date) ? date.to_date : date).wday
+      end
+
+      def sunday(date)
+        date + days(7 - weekday(date))
+      end
+
+      def midnight(date)
+        set_time(date, 23, 59, 59)
+      end
+
+      def daystart(date)
+        set_time(date, 0, 0, 0)
+      end
+
+      def previous_sunday(date)
+        midnight(sunday(date - weeks(1)))
+      end
+
+      def this_monday(date)
+        set_time(previous_sunday(date) + days(1), 0, 0, 0)
+      end
+
+      # Resolve a filter [key, name] pair for the register search.
+      #
+      # @note **Search-key gotcha:** the register search matches on the field DEFINITION key,
+      #   not the field's name/label. For a data-field object we therefore prefer its backend
+      #   reference key. The exact GraphQL accessor is duck-typed here (ref_backend -> key) and
+      #   must be confirmed against the live field model before relying on field-scoped search
+      #   filters (a wrong key silently matches 0 rows). See the CANS search-key note.
+      def field_key_name(value)
+        case value
+        when :updated_at then ["updated_at", "Last updated"]
+        when :created_at then ["created_at", "Page created"]
+        when :tags       then ["tags", "Location Tags"]
+        else
+          if value.respond_to?(:ref_backend)
+            [value.ref_backend, (value.respond_to?(:label) ? value.label : nil)]
+          elsif value.respond_to?(:key)
+            [value.key, (value.respond_to?(:label) ? value.label : nil)]
+          else
+            [nil, nil]
+          end
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Lint/SymbolConversion, Style/QuotedSymbols