eco-helpers 3.2.16 → 3.2.17

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy/sync_readiness.rb

@@ -0,0 +1,178 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module Deploy
+    # Sync-readiness monitoring.
+    #
+    # Given a register subset (its entries) and the register's ACTIVE template, report which entries
+    # CAN sync vs which cannot — where "can sync" means: every field the template marks REQUIRED is
+    # present on the entry with a non-empty value AND typed correctly (the entry field's type matches
+    # the template field's type). This is the pre-flight an integration runs before pushing entries
+    # downstream, and the drift-detection the customer-facing integrations mandate needs.
+    #
+    # Operates on raw docs (template doc + entry docs) so it is session-less and offline-runnable:
+    #   * template doc: the JSON the gem returns for a template (stages/sections/dataFields).
+    #   * entry docs:   each register entry as { 'id' =>, 'fields' => [ {id/label/type/value}, ... ] }
+    #     (or anything exposing the same shape). A field is matched to a template field by id first,
+    #     then by label — mirroring how the pairing engine falls back.
+    #
+    #   monitor = SyncReadiness.new(template_doc: tpl, entries: [e1, e2, ...])
+    #   monitor.ready         # => [EntryReadiness(ready: true), ...]
+    #   monitor.not_ready     # => [EntryReadiness(ready: false, ...), ...]
+    #   monitor.summary       # => { total:, ready:, not_ready: }
+    #   monitor.report        # => human summary
+    class SyncReadiness
+      # Per-entry readiness verdict.
+      EntryReadiness = Struct.new(:entry_id, :ready, :missing_required, :type_mismatches,
+                                  keyword_init: true) do
+        def ready?
+          ready ? true : false
+        end
+
+        def reasons
+          out = Array(missing_required).map { |m| "missing required '#{m}'" }
+          Array(type_mismatches).each do |m|
+            out << "type mismatch '#{m[:label]}' (want #{m[:expected]}, got #{m[:actual]})"
+          end
+          out
+        end
+
+        def to_h
+          { entry_id: entry_id, ready: ready?, missing_required: Array(missing_required),
+            type_mismatches: Array(type_mismatches) }
+        end
+      end
+
+      attr_reader :entries
+
+      # @param template_doc [Hash] the active template doc.
+      # @param entries [Array<Hash,#id>] register entry docs to assess.
+      def initialize(template_doc:, entries:)
+        @template_doc = template_doc || {}
+        @entries      = Array(entries)
+      end
+
+      def verdicts
+        @verdicts ||= @entries.map { |entry| assess(entry) }
+      end
+
+      def ready
+        verdicts.select(&:ready?)
+      end
+
+      def not_ready
+        verdicts.reject(&:ready?)
+      end
+
+      def summary
+        { total: verdicts.size, ready: ready.size, not_ready: not_ready.size }
+      end
+
+      def to_h
+        { summary: summary, entries: verdicts.map(&:to_h) }
+      end
+
+      def report
+        lines = ["SYNC READINESS: #{summary[:ready]}/#{summary[:total]} entries ready"]
+        not_ready.each do |v|
+          lines << "  * entry #{v.entry_id}: NOT READY"
+          v.reasons.each { |r| lines << "      - #{r}" }
+        end
+        lines.join("\n")
+      end
+
+      private
+
+      # The template fields, indexed by id and by (downcased) label, carrying type + required.
+      def template_fields
+        @template_fields ||= begin
+          out = { by_id: {}, by_label: {} }
+          each_template_field do |f|
+            spec = { id: f['id'], label: f['label'], type: field_type(f), required: !!f['required'] }
+            out[:by_id][f['id']] = spec if f['id']
+            out[:by_label][label_key(f['label'])] = spec if f['label']
+          end
+          out
+        end
+      end
+
+      def required_fields
+        @required_fields ||= template_fields[:by_id].values.select { |s| s[:required] }.
+          +(template_fields[:by_label].values.select { |s| s[:required] }).
+          uniq { |s| s[:id] || s[:label] }
+      end
+
+      def assess(entry)
+        entry_fields = index_entry_fields(entry)
+        missing      = []
+        mismatches   = []
+
+        required_fields.each do |spec|
+          efield = entry_fields[:by_id][spec[:id]] || entry_fields[:by_label][label_key(spec[:label])]
+          if efield.nil? || value_empty?(efield[:value])
+            missing << spec[:label]
+          elsif spec[:type] && efield[:type] && spec[:type] != efield[:type]
+            mismatches << { label: spec[:label], expected: spec[:type], actual: efield[:type] }
+          end
+        end
+
+        EntryReadiness.new(
+          entry_id:         entry_id(entry),
+          ready:            missing.empty? && mismatches.empty?,
+          missing_required: missing,
+          type_mismatches:  mismatches
+        )
+      end
+
+      def index_entry_fields(entry)
+        out = { by_id: {}, by_label: {} }
+        entry_field_docs(entry).each do |f|
+          spec = { id: f['id'] || f[:id], label: f['label'] || f[:label],
+                   type: field_type(f), value: f['value'] || f[:value] }
+          out[:by_id][spec[:id]]                    = spec if spec[:id]
+          out[:by_label][label_key(spec[:label])]   = spec if spec[:label]
+        end
+        out
+      end
+
+      def entry_field_docs(entry)
+        return Array(entry['fields'] || entry[:fields]) if entry.is_a?(Hash)
+        return entry.components.to_a if entry.respond_to?(:components)
+
+        []
+      end
+
+      def entry_id(entry)
+        return entry['id'] || entry[:id] if entry.is_a?(Hash)
+
+        entry.respond_to?(:id) ? entry.id : nil
+      end
+
+      def each_template_field(&block)
+        Array(@template_doc['stages']).each do |st|
+          Array(st['sections']).each do |sec|
+            fields_of(sec).each(&block)
+          end
+        end
+      end
+
+      def fields_of(section)
+        Array(section['dataFields']) + Array(section['leftDataFields']) + Array(section['rightDataFields'])
+      end
+
+      def field_type(field)
+        field['__typename'] || field['type'] || field[:type]
+      end
+
+      def label_key(label)
+        label.to_s.strip.downcase
+      end
+
+      def value_empty?(value)
+        return true if value.nil?
+        return value.strip.empty? if value.is_a?(String)
+        return value.empty? if value.respond_to?(:empty?)
+
+        false
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy/verifier.rb

@@ -0,0 +1,141 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module Deploy
+    # Pluggable post-deploy verification interface.
+    #
+    # The deploy loop wants to run the freshly-deployed template through a check framework (ideally the
+    # `ecoportal-qa` gem's check runner). But `ecoportal-qa` is NOT a hard dependency of eco-helpers,
+    # so we do not `require` it here. Instead the loop calls a small `Verifier` interface; a concrete
+    # verifier is injected. When `ecoportal-qa` IS on the load path, `QaVerifier` wires it in; when it
+    # isn't, `NullVerifier` (always-pass, records that qa was unavailable) keeps the loop runnable
+    # offline.
+    #
+    # A verifier receives the post-deploy template doc and returns a `Verdict`.
+    #
+    #   verdict = Verifier.default.verify(post_deploy_doc)
+    #   verdict.pass?      # => true/false
+    #   verdict.findings   # => [ {severity:, message:}, ... ]
+    class Verifier
+      # A verification verdict. `pass?` is the gate; `findings` carries per-check detail.
+      Verdict = Struct.new(:pass, :findings, :verifier, keyword_init: true) do
+        def pass?
+          pass ? true : false
+        end
+
+        def failures
+          Array(findings).select { |f| %i[error fail].include?((f[:severity] || f['severity'])&.to_sym) }
+        end
+
+        def to_h
+          { pass: pass?, verifier: verifier, findings: Array(findings) }
+        end
+
+        def report
+          head = "VERIFY (#{verifier}): #{pass? ? 'PASS' : 'FAIL'}"
+          return head if Array(findings).empty?
+
+          ([head] + Array(findings).map do |f|
+            "  - [#{f[:severity] || f['severity']}] #{f[:message] || f['message']}"
+          end).join("\n")
+        end
+      end
+
+      # The verifier the loop uses when none is injected: qa if available, else the null verifier.
+      def self.default
+        qa_available? ? QaVerifier.new : NullVerifier.new
+      end
+
+      # Is the ecoportal-qa check framework loadable?
+      def self.qa_available?
+        return @qa_available unless @qa_available.nil?
+
+        @qa_available = begin
+          require 'ecoportal/qa'
+          defined?(::Ecoportal::QA) ? true : false
+        rescue LoadError
+          false
+        end
+      end
+
+      # Reset the memoised availability probe (used by specs that stub the load path).
+      def self.reset_qa_probe!
+        @qa_available = nil
+      end
+
+      # Subclass / duck-type contract: return a Verdict for the given template doc.
+      def verify(_template_doc)
+        raise NotImplementedError, "#{self.class} must implement #verify(template_doc)"
+      end
+
+      # Always-pass verifier used when no real check framework is wired in. It is honest about it:
+      # the verdict records that qa was unavailable so a report never falsely claims "qa verified".
+      class NullVerifier < Verifier
+        def verify(_template_doc)
+          Verdict.new(
+            pass:     true,
+            verifier: 'null',
+            findings: [{ severity: :info, message: 'ecoportal-qa not available; no checks run' }]
+          )
+        end
+      end
+
+      # Adapter onto the ecoportal-qa check runner. Kept dependency-free at load time — it only touches
+      # `Ecoportal::QA` inside #verify, so requiring this file never forces the qa gem. The exact qa
+      # runner API is intentionally accessed through a single seam (`run_qa`) so it is easy to correct
+      # once the qa public surface stabilises (see TODO).
+      #
+      # TODO(qa-integration): the qa check-runner public API is still moving (see the qa repo's
+      # PHASE3-SCOPE.md). This adapter assumes a `check_set.run(doc)`-style entry returning objects
+      # responding to `#pass?` and `#findings`. Confirm and adjust `run_qa` when qa is pinned as a dep.
+      class QaVerifier < Verifier
+        def initialize(check_set: nil)
+          super()
+          @check_set = check_set
+        end
+
+        def verify(template_doc)
+          result = run_qa(template_doc)
+          Verdict.new(pass: result_pass?(result), verifier: 'ecoportal-qa', findings: result_findings(result))
+        rescue StandardError => e
+          Verdict.new(pass: false, verifier: 'ecoportal-qa',
+                      findings: [{ severity: :error, message: "qa verification raised: #{e.message}" }])
+        end
+
+        private
+
+        # SINGLE integration seam — the one place that knows the qa runner shape.
+        def run_qa(template_doc)
+          set = @check_set || default_check_set
+          set.run(template_doc)
+        end
+
+        def default_check_set
+          raise NotImplementedError, 'no qa check_set injected and no default wired' unless defined?(::Ecoportal::QA)
+
+          # Placeholder: the concrete constructor is confirmed once qa is a pinned dependency.
+          if ::Ecoportal::QA.respond_to?(:default_check_set)
+            ::Ecoportal::QA.default_check_set
+          else
+            (raise NotImplementedError,
+                   'qa default check set not available')
+          end
+        end
+
+        def result_pass?(result)
+          return result.pass? if result.respond_to?(:pass?)
+
+          Array(result).all? { |r| r.respond_to?(:pass?) ? r.pass? : true }
+        end
+
+        def result_findings(result)
+          source = result.respond_to?(:findings) ? result.findings : result
+          Array(source).map do |f|
+            next f if f.is_a?(Hash)
+
+            { severity: (f.respond_to?(:severity) ? f.severity : :info),
+              message:  (f.respond_to?(:message) ? f.message : f.to_s) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy.rb

@@ -0,0 +1,21 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  # Phase 5: deploy → verify → monitor loop for template (workflow) changes.
+  #
+  # Consumes a gem `Ecoportal::API::GraphQL::Diff::Deploy` command batch (from
+  # `Diff::Deploy.from_versions(...)`), dry-run applies it (live behind an explicit `commit:` flag),
+  # confirms the applied delta matches the intended delta via a pre/post self-version diff
+  # (`Diff::VersionDiff`), verifies the result through a pluggable `Verifier` (ecoportal-qa when
+  # present), and reports register sync-readiness against the deployed template.
+  #
+  # All components are session-less and offline-runnable against fixtures — the live seams (apply /
+  # re-read) are injected. See each file's header. Dry-run is the DEFAULT.
+  module Deploy
+  end
+end
+
+require_relative 'deploy/applier'
+require_relative 'deploy/recording_executor'
+require_relative 'deploy/drift_report'
+require_relative 'deploy/verifier'
+require_relative 'deploy/sync_readiness'
+require_relative 'deploy/loop'

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

@@ -0,0 +1,11 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Template (workflow) build-from-scratch + (later) diff-and-update samples.
+  # See ecoportal-api-graphql/.ai-assistance/projects/template-maintenance/.
+  module Template
+  end
+end
+
+require_relative 'template/command_emitter'
+require_relative 'template/base'
+require_relative 'template/csv_build'
+require_relative 'template/deploy'

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

@@ -4,4 +4,6 @@ module Eco::API::UseCases::GraphQL::Samples
 end
 
 require_relative 'pages/page'
+require_relative 'pages/register'
 require_relative 'pages/org_page'
+require_relative 'pages/template'

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = '3.2.16'.freeze
+  VERSION = '3.2.17'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.2.16
+  version: 3.2.17
 platform: ruby
 authors:
 - Oscar Segura
@@ -262,7 +262,7 @@ dependencies:
         version: '1.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.9
+        version: 1.3.11
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -272,7 +272,7 @@ dependencies:
         version: '1.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.9
+        version: 1.3.11
 - !ruby/object:Gem::Dependency
   name: ecoportal-api-v2
   requirement: !ruby/object:Gem::Requirement
@@ -282,7 +282,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.1
+        version: 3.3.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -292,7 +292,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.1
+        version: 3.3.3
 - !ruby/object:Gem::Dependency
   name: ed25519
   requirement: !ruby/object:Gem::Requirement
@@ -844,6 +844,9 @@ files:
 - lib/eco/api/usecases/graphql/compat/ooze_redirect/dirty_array.rb
 - lib/eco/api/usecases/graphql/compat/ooze_redirect/field_patches.rb
 - lib/eco/api/usecases/graphql/compat/ooze_redirect/force_compat.rb
+- lib/eco/api/usecases/graphql/compat/parity/comparison.rb
+- lib/eco/api/usecases/graphql/compat/parity/harness.rb
+- lib/eco/api/usecases/graphql/compat/parity/run_result.rb
 - lib/eco/api/usecases/graphql/helpers.rb
 - lib/eco/api/usecases/graphql/helpers/CLAUDE.md
 - lib/eco/api/usecases/graphql/helpers/base.rb
@@ -877,6 +880,14 @@ files:
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap.rb
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap/tags_map.rb
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap/tags_set.rb
+- lib/eco/api/usecases/graphql/helpers/pages.rb
+- lib/eco/api/usecases/graphql/helpers/pages/copying.rb
+- lib/eco/api/usecases/graphql/helpers/pages/creatable.rb
+- lib/eco/api/usecases/graphql/helpers/pages/filters.rb
+- lib/eco/api/usecases/graphql/helpers/pages/ooze_handlers.rb
+- lib/eco/api/usecases/graphql/helpers/pages/rescuable.rb
+- lib/eco/api/usecases/graphql/helpers/pages/shortcuts.rb
+- lib/eco/api/usecases/graphql/helpers/pages/typed_fields_pairing.rb
 - lib/eco/api/usecases/graphql/samples.rb
 - lib/eco/api/usecases/graphql/samples/CLAUDE.md
 - lib/eco/api/usecases/graphql/samples/contractors.rb
@@ -913,6 +924,24 @@ files:
 - lib/eco/api/usecases/graphql/samples/pages/page.rb
 - lib/eco/api/usecases/graphql/samples/pages/page/base.rb
 - lib/eco/api/usecases/graphql/samples/pages/page/dsl.rb
+- lib/eco/api/usecases/graphql/samples/pages/register.rb
+- lib/eco/api/usecases/graphql/samples/pages/register/base.rb
+- lib/eco/api/usecases/graphql/samples/pages/register/migration_case.rb
+- lib/eco/api/usecases/graphql/samples/pages/register/target_oozes_update_case.rb
+- lib/eco/api/usecases/graphql/samples/pages/template.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/base.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/command_emitter.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/csv_build.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/csv_build/builder.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/csv_build/format_map.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/csv_build/parser.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/applier.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/drift_report.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/loop.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/recording_executor.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/sync_readiness.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/verifier.rb
 - lib/eco/api/usecases/graphql/utils.rb
 - lib/eco/api/usecases/graphql/utils/sftp.rb
 - lib/eco/api/usecases/lib.rb