eco-helpers 3.2.14 → 3.2.23

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

@@ -0,0 +1,303 @@
+module Eco::API::UseCases::GraphQL::Helpers
+  module Pages
+    # Native GraphQL re-expression of
+    # OozeSamples::HelpersMigration::TypedFieldsPairing.
+    #
+    # It pairs fields of the SAME type with the SAME label name across two page
+    # models (a source `src` and a destination `dst`). This is the cross-template
+    # field-pairing used by migration cases — DISTINCT from the value-merge
+    # `OozeHandlers#merge_values` (which combines two values of one already-paired
+    # field).
+    #
+    # It runs two screenings:
+    #   (1) exact label match,
+    #   (2) then the rest, case-insensitive a-z only, content between brackets removed.
+    #
+    # Other features (ported verbatim from the v2 "World Wonder of 2022"):
+    #   * tracks src / dst fields that were NOT paired
+    #   * lets you `resolve` fields paired by other means out of the unpaired sets
+    #   * tracks src fields with MULTIPLE candidate dst fields (`src_dst_multi`)
+    #
+    # == What differs from the v2 class
+    #
+    # Fields are grouped and compared by the GraphQL DataField TYPE STRING (the
+    # `__typename`-derived value in `Ecoportal::API::GraphQL::Base::Page::DataField::TYPE_MAP`,
+    # e.g. 'PlainText', 'Select', 'Date') rather than the v2 snake_case component type
+    # (`'plain_text'`, `'select'`, `'date'`). Same-type grouping still guarantees a
+    # pair only forms between fields of identical type. `EXCLUDED_TYPES` therefore
+    # lists the GraphQL type strings for the never-pair types (charts / tag fields).
+    #
+    # `ximport?` detects an import-marker field via its `#tooltip` (unchanged), and
+    # `object_reference` / `same_string?` come from the native `Shortcuts`.
+    class TypedFieldsPairing
+      include Eco::API::UseCases::GraphQL::Helpers::Pages::Shortcuts
+
+      # GraphQL DataField type strings that must never be paired (no meaningful,
+      # copyable content). Mirrors the v2 EXCLUDED_TYPES
+      # (%w[tag_field chart frequency_rate_chart]) in GraphQL terms — GraphQL has no
+      # distinct chart data-field types, so TagField is the practical excluded type;
+      # any additional non-content types can be added here.
+      EXCLUDED_TYPES = %w[TagField Chart FrequencyRateChart].freeze
+
+      attr_reader :src, :dst
+      attr_reader :src_unpaired, :dst_unpaired
+      attr_reader :src_dst_pairs, :src_dst_multi
+
+      def initialize(source, destination, src_excluded: nil, dst_excluded: nil,
+          exclude_ximport: false)
+        @src             = source
+        @dst             = destination
+        @src_excluded    = src_excluded || []
+        @dst_excluded    = dst_excluded || []
+        @exclude_ximport = exclude_ximport
+
+        reset!
+        process(exact: true)
+        process
+      end
+
+      def each_pair
+        src_dst_pairs.each do |(src_field, dst_field)|
+          yield(src_field, dst_field) if block_given?
+        end
+      end
+
+      def report_src_unpaired(only_present: true, only_indexed: false)
+        return if src_unpaired.empty?
+
+        msg = "Source entry with unpaired fields (#{object_reference(src)}):\n"
+
+        src_filtered = src_unpaired.values.flatten.reject do |src_fld|
+          only_present && field_empty?(src_fld)
+        end.reject do |src_fld|
+          only_indexed && src_fld.deindex
+        end
+
+        return if src_filtered.empty?
+
+        msg << src_filtered.map do |src_fld|
+          "  * #{object_reference(src_fld)}"
+        end.join("\n")
+      end
+
+      def report_dst_unpaired(only_required: false, exclude_ximport: true)
+        return if dst_unpaired.empty?
+
+        msg = "Destination entry with unpaired fields (#{object_reference(src)}):\n"
+
+        dst_filtered = dst_unpaired.values.flatten.reject do |dst_fld|
+          only_required && !dst_fld.required
+        end.reject do |dst_fld|
+          exclude_ximport && ximport?(dst_fld)
+        end
+
+        return if dst_filtered.empty?
+
+        msg << dst_filtered.map do |dst_fld|
+          "  * #{object_reference(dst_fld)}"
+        end.join("\n")
+      end
+
+      def report_multi_pairs(only_present: true, only_indexed: false, dst_exclude_ximport: true)
+        return nil if src_dst_multi.empty?
+
+        ''.tap do |msg|
+          msg     << "Source fields in (#{object_reference(src)}) paired with multiple destination fields:\n"
+          msg_flds = ''
+          src_dst_multi.each_value do |pairs|
+            pairs.each do |(src_fld, dst_flds)|
+              next if (only_present && field_empty?(src_fld)) || (only_indexed && src_fld.deindex)
+
+              dst_filtered = dst_flds.reject do |dst_fld|
+                dst_exclude_ximport && ximport?(dst_fld)
+              end
+              next if dst_filtered.empty?
+
+              msg_flds << "  * #{object_reference(src_fld)}\n"
+              msg_flds << dst_filtered.map do |dst_fld|
+                "    * #{object_reference(dst_fld)}"
+              end.compact.join("\n")
+            end
+          end
+
+          return nil if msg_flds.empty?
+
+          msg << msg_flds
+        end
+      end
+
+      # Remove from unpaired tracking those `flds`.
+      def resolve(*flds)
+        flds.each do |fld|
+          next if unpaired_delete?(fld, src_unpaired)
+
+          unpaired_delete?(fld, dst_unpaired)
+        end
+
+        multi_delete(*flds)
+      end
+
+      def some_multi?
+        !src_dst_multi.empty?
+      end
+
+      private
+
+      # When comparing, use only a-z letters.
+      def only_letters?
+        true
+      end
+
+      # When comparing, remove anything between brackets from the field label name.
+      def non_bracked?
+        true
+      end
+
+      # If `false`, it compares with all lower case.
+      def exact?
+        !(only_letters? || non_bracked?)
+      end
+
+      def process(exact: false)
+        src_unpaired.each do |type, src_pend|
+          next unless (dst_pend = dst_unpaired[type]) && !dst_pend.empty?
+
+          src_pend.dup.each do |src_fld|
+            dst_candidates = dst_pend.select do |dst_fld|
+              str_eq?(src_fld.label, dst_fld.label, exact: exact)
+            end
+            next if dst_candidates.empty?
+
+            if dst_candidates.one?
+              pair_add(src_fld, dst_candidates.first)
+            else
+              multi_add(type, src_fld, *dst_candidates)
+            end
+          end
+        end
+      end
+
+      def str_eq?(str_1, str_2, exact: false)
+        same_string?(str_1, str_2, **str_eq_params, exact: exact)
+      end
+
+      def str_eq_params
+        {
+          exact:  exact?,
+          mild:   only_letters?,
+          ignore: false
+        }.tap do |params|
+          params.merge!(ignore: bracked_regex) if non_bracked?
+        end
+      end
+
+      def pair_add(src_fld, dst_fld)
+        resolve(src_fld, dst_fld)
+        src_dst_pairs << [src_fld, dst_fld]
+      end
+
+      # Removes a field from a (src or dst) unpaired set.
+      # @return [Boolean] true when the field was present and removed.
+      def unpaired_delete?(fld, unpaired)
+        type = fld.type
+        return false unless unpaired.key?(type)
+        return false unless (flds = unpaired[type]).delete(fld)
+
+        unpaired.delete(type) if flds.empty?
+        true
+      end
+
+      def multi_add(type, src_fld, *dst_flds)
+        (src_dst_multi[type] ||= []) << (pair = [src_fld, dst_flds])
+        @src_multi[src_fld]          = pair
+
+        dst_flds.each do |dst_fld|
+          (@dst_multi[dst_fld] ||= []) << pair
+        end
+      end
+
+      def multi_delete(*flds)
+        flds.each do |fld|
+          next unless (type_pairs = src_dst_multi[fld.type])
+
+          if (pairs = @dst_multi.delete(fld))
+            pairs.each do |pair|
+              src_fld  = pair.first
+              dst_flds = pair.last
+              dst_flds.delete(fld)
+              if dst_flds.empty?
+                @src_multi.delete(src_fld)
+                type_pairs.delete(pair)
+              end
+            end
+          elsif @src_multi.key?(fld)
+            pair = @src_multi.delete(fld)
+            type_pairs.delete(pair)
+
+            pair.last.each do |dst_fld|
+              pairs = @dst_multi[dst_fld]
+              pairs.delete(pair)
+              @dst_multi.delete(dst_fld) if pairs.empty?
+            end
+          end
+
+          src_dst_multi.delete(fld.type) if type_pairs.empty?
+        end
+      end
+
+      def by_type(components)
+        components.to_a.group_by(&:type).tap do |out|
+          EXCLUDED_TYPES.each {|type| out.delete(type)}
+        end
+      end
+
+      def src_components
+        flds = components_of(src)
+        flds = flds.reject {|fld| ximport?(fld)} if @exclude_ximport
+        flds - @src_excluded
+      end
+
+      def dst_components
+        flds = components_of(dst)
+        flds = flds.reject {|fld| ximport?(fld)} if @exclude_ximport
+        flds - @dst_excluded
+      end
+
+      # Duck-typed access to a page model's data fields. Native GraphQL page
+      # models expose `#components` (a SectionCollection-backed collection); the
+      # v2 class relied on the same method name.
+      def components_of(entry)
+        entry.components.to_a
+      end
+
+      def ximport?(fld)
+        return false unless fld.respond_to?(:tooltip)
+
+        fld.tooltip.to_s.include?('ximport')
+      end
+
+      # A field is "empty" when it carries no content. Native DataField types do
+      # not universally expose `#empty?`; fall back to `#value` emptiness so the
+      # report filters behave like the v2 ones.
+      def field_empty?(fld)
+        return fld.empty? if fld.respond_to?(:empty?)
+        return fld.value.to_s.strip.empty? if fld.respond_to?(:value)
+
+        false
+      end
+
+      def reset!
+        @src_unpaired  = by_type(src_components)
+        @dst_unpaired  = by_type(dst_components)
+        @src_dst_pairs = []
+        reset_multi!
+      end
+
+      def reset_multi!
+        @src_dst_multi = {}
+        @src_multi     = {}
+        @dst_multi     = {}
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Eco::API::UseCases::GraphQL::Helpers
+  # Native GraphQL page-processing helper substrate.
+  #
+  # These mirror the *pure* parts of Eco::API::UseCases::OozeSamples::Helpers::* but drop the
+  # Ecoportal::API::V2 coupling: string/date utilities are ported verbatim, while the few
+  # methods that inspected V2 model types (object_reference, field_key_name) are re-expressed
+  # with duck-typing so they work against the GraphQL page/section/field models.
+  #
+  # This is Phase 1 of the ooze -> native GraphQL migration (build the shared substrate before
+  # any case). See the ecoportal-api-graphql repo's internal docs.
+  module Pages
+  end
+end
+
+require_relative 'pages/shortcuts'
+require_relative 'pages/filters'
+require_relative 'pages/ooze_handlers'
+require_relative 'pages/rescuable'
+require_relative 'pages/creatable'
+require_relative 'pages/typed_fields_pairing'
+require_relative 'pages/copying'

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

@@ -6,3 +6,4 @@ end
 require_relative 'helpers/base'
 require_relative 'helpers/location'
 require_relative 'helpers/contractors'
+require_relative 'helpers/pages'

data/lib/eco/api/usecases/graphql/samples/location/command/service/tree_update.rb

@@ -57,7 +57,7 @@ class Eco::API::UseCases::GraphQL::Samples::Location
           digest_msgs  << "\n#{exception.patch_full_message(trace_count: 3)}" if exception
 
           session.mail(subject: subject, body: digest_msgs.join).tap do
-            options.deep_merge!({worfklow: {no_email: true}})
+            options.deep_merge!({workflow: {no_email: true}})
           end
         end
       end

data/lib/eco/api/usecases/graphql/samples/pages/org_page/base.rb

@@ -0,0 +1,41 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Base class for **org-wide** page processing use cases.
+  #
+  # Identical to Page::Base but with no default register scope — search_conf
+  # starts empty (all org pages). Subclass adds filters via super.
+  #
+  # == When to use which
+  #
+  #   Page::Base    — one register, most scripts ("go through all pages in Reg X")
+  #   OrgPage::Base — entire org (cross-register audits, archive sweeps, bulk ops)
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::ArchiveStaleDrafts < Eco::API::UseCases::GraphQL::Samples::Pages::OrgPage::Base
+  #     name 'archive-stale-drafts'
+  #     batch_size 100
+  #
+  #     def search_conf
+  #       super.filter(state_is(:draft))
+  #            .filter(updated_since('2025-01-01'))
+  #     end
+  #
+  #     def process_page(page)
+  #       return skip('already archived') if page.archived?
+  #       log(:info) { "Archiving: #{page.name}" }
+  #       graphql.page.archive(input: { id: page.id }) unless simulate?
+  #     end
+  #   end
+  class OrgPage::Base < Page::Base
+    name 'graphql-org-page-base'
+    type :other
+
+    require_relative 'dsl'
+    include Eco::API::UseCases::GraphQL::Samples::Pages::OrgPage::DSL
+
+    # No default register scope. Subclass adds filters via super.
+    def search_conf
+      sc.new
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/org_page/dsl.rb

@@ -0,0 +1,8 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::OrgPage
+  # DSL concern for org-wide page use cases.
+  # Includes Page::DSL — all SearchConf helpers are available.
+  # Add org-page-specific helpers here as the pattern grows.
+  module DSL
+    include Eco::API::UseCases::GraphQL::Samples::Pages::Page::DSL
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/org_page.rb

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  module OrgPage
+  end
+end
+
+require_relative 'org_page/dsl'
+require_relative 'org_page/base'

data/lib/eco/api/usecases/graphql/samples/pages/page/base.rb

@@ -0,0 +1,148 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Base class for **register-scoped** page processing use cases.
+  #
+  # Provides the iteration + KPI scaffolding mirroring RegisterUpdateCase
+  # from OozeSamples, but working natively with the GraphQL stack.
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::UpdateRiskRating < Eco::API::UseCases::GraphQL::Samples::Pages::Page::Base
+  #     name 'update-risk-rating'
+  #     register_id 'REG_ABC123'
+  #     batch_size 50
+  #
+  #     # Add filters on top of the default register scope.
+  #     def search_conf
+  #       super.filter(state_is(:active))
+  #            .filter(updated_since(options.dig(:filters, :from).to_s))
+  #     end
+  #
+  #     # Transform or act on each page; call update_page(page) to persist.
+  #     def process_page(page)
+  #       field = page.components.get_by_name('Risk Level')
+  #       return skip('no risk field') unless field
+  #       page.name = "[HIGH] #{page.name}" if field.value == 'High'
+  #       update_page(page)
+  #     end
+  #   end
+  #
+  # == What the base provides
+  # * process_page(page) — override point (required)
+  # * search_conf        — override point (optional; default scopes to register_id)
+  # * update_page(page)  — from_model + simulate? guard + error tracking
+  # * skip(reason)       — record a non-error skip
+  # * each_page          — cursor-paginated org search
+  # * KPI tracking       — total / processed / updated / skipped / failed
+  class Page::Base < Eco::API::UseCases::GraphQL::Base
+    name 'graphql-page-base'
+    type :other
+
+    require_relative 'dsl'
+    include Eco::API::UseCases::GraphQL::Samples::Pages::Page::DSL
+
+    class << self
+      def batch_size(size = nil)
+        @batch_size ||= 50
+        return @batch_size unless size
+        @batch_size = size
+      end
+
+      def register_id(id = nil)
+        @register_id = id if id
+        @register_id
+      end
+    end
+
+    attr_reader :total_pages, :processed_pages, :updated_pages
+    attr_reader :failed_pages, :skipped_pages
+
+    # Entry point — called by GraphQL::Base#main.
+    def process
+      init_kpis
+      each_page do |page|
+        process_page(page)
+        @processed_pages += 1
+      end
+      log_kpis
+    end
+
+    # == Subclass override points ==============================================
+
+    # Transform or act on one page. Call update_page(page) to persist changes.
+    def process_page(_page)
+      raise NotImplementedError, "Implement #process_page in #{self.class}"
+    end
+
+    # Return a SearchConf for the page search. Override to add filters.
+    # Default: scoped to register_id when set, otherwise all pages.
+    def search_conf
+      conf = sc.new
+      reg  = self.class.register_id
+      conf = conf.filter(in_register(reg)) if reg
+      conf
+    end
+
+    protected
+
+    # Record a skip (not an error — the page was intentionally not processed).
+    def skip(reason = nil)
+      @skipped_pages += 1
+      log(:debug) { "Skipped#{reason ? ": #{reason}" : ''}" }
+    end
+
+    # Persist a page. Wraps Input::Page::Update.from_model, respects simulate?,
+    # and tracks KPIs. Returns nil on simulate or no-change; Response otherwise.
+    def update_page(page, **kargs)
+      if simulate?
+        @skipped_pages += 1
+        log(:debug) { "Simulate — would update page #{page.id}" }
+        return nil
+      end
+      response = graphql.pages.update(page, **kargs)
+      if response.nil?
+        @skipped_pages += 1
+      elsif response.success?
+        @updated_pages += 1
+      else
+        @failed_pages += 1
+        log(:error) { "Failed to update page #{page.id}: #{response.body}" }
+      end
+      response
+    end
+
+    # Cursor-paginated iteration over pages matching search_conf.
+    # Uses org search (currentOrganization.pages) — returns full PageUnion
+    # with patchVer and field IDs (required for update workflows).
+    def each_page(conf: search_conf, first: self.class.batch_size, &block)
+      graphql.pages.each(search_conf: conf.to_h, first: first) do |page|
+        @total_pages += 1
+        yield page
+      end
+    end
+
+    private
+
+    def init_kpis
+      @total_pages     = 0
+      @processed_pages = 0
+      @updated_pages   = 0
+      @failed_pages    = 0
+      @skipped_pages   = 0
+    end
+
+    def log_kpis
+      log(:info) { kpis_message }
+    end
+
+    def kpis_message
+      [
+        'Run end:',
+        "  * Pages found:     #{total_pages}",
+        "  * Pages processed: #{processed_pages}",
+        "  * Updated:         #{updated_pages}",
+        "  * Skipped:         #{skipped_pages}",
+        "  * Failed:          #{failed_pages}"
+      ].join("\n")
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/page/dsl.rb

@@ -0,0 +1,38 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Page
+  # DSL concern — included in Page::Base and available to all Page subclasses.
+  # Provides the SearchConf accessor and common filter shorthand methods.
+  #
+  # Include this in any class that needs SearchConf DSL access without
+  # inheriting the full Page::Base iteration scaffolding.
+  module DSL
+    private
+
+    # Lazy accessor for the SearchConf builder class.
+    # Resolved at runtime so the ecoportal-api-graphql gem is guaranteed to be loaded.
+    # Subclasses can also define a local constant for brevity:
+    #   SearchConf = Ecoportal::API::GraphQL::Input::SearchConf
+    def sc
+      Ecoportal::API::GraphQL::Input::SearchConf
+    end
+
+    # Convenience: build a register-scoped filter object.
+    def in_register(*ids)
+      sc.in_register(*ids)
+    end
+
+    # Convenience: build a state equality filter.
+    def state_is(value)
+      sc[:state].is(value)
+    end
+
+    # Convenience: build an externalId equality filter.
+    def external_id_eq(value)
+      sc[:external_id].eq(value)
+    end
+
+    # Convenience: build an updated_at since filter.
+    def updated_since(iso8601, time_zone: 'UTC')
+      sc[:updated_at].since(iso8601, time_zone: time_zone)
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/page.rb

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  module Page
+  end
+end
+
+require_relative 'page/dsl'
+require_relative 'page/base'