lcp 0.1.0

data/lib/lcp_ruby/widgets/data_resolver.rb

@@ -0,0 +1,676 @@
+module LcpRuby
+  module Widgets
+    class DataResolver
+      include ScopeApplicator
+
+      WidgetScope = Struct.new(:model_class, :model_def, :evaluator, :base_scope, :scope, keyword_init: true)
+
+      def initialize(zone, user:, scope_context: nil,
+                     filter_form: nil, scope_filter_set: nil, record: nil)
+        @zone = zone
+        @user = user
+        @scope_context = scope_context || {}
+        @filter_form = filter_form
+        @scope_filter_set = scope_filter_set
+        @record = record
+      end
+
+      def resolve
+        widget = @zone.widget
+        return { hidden: true } unless widget
+
+        case widget["type"]
+        when "kpi_card" then resolve_kpi_card(widget)
+        when "text"     then resolve_text(widget)
+        when "list"     then resolve_list(widget)
+        when "chart"    then resolve_chart(widget)
+        when "embed"    then resolve_embed(widget)
+        when "workflow_graph" then resolve_workflow_graph(widget)
+        when "approval_status" then resolve_approval_status
+        else { hidden: true }
+        end
+      end
+
+      private
+
+      def resolve_kpi_card(widget)
+        # Metric-based KPI card (reads from Prometheus registry)
+        if widget["value_source"]
+          return resolve_metric_kpi_card(widget)
+        end
+
+        ws = build_widget_scope(widget)
+        return { hidden: true } unless ws
+
+        aggregate = widget["aggregate"]&.to_sym
+        aggregate_field = widget["aggregate_field"]
+
+        value = compute_aggregate(ws.scope, aggregate, aggregate_field)
+
+        result = {
+          value: value,
+          label: widget_label(widget),
+          icon: widget["icon"],
+          link_to: widget["link_to"],
+          format: widget["format"]
+        }
+
+        if widget["compare_scope"].present?
+          compare_value = compute_comparison(ws, widget)
+          result.merge!(trend_data(value, compare_value))
+        end
+
+        result
+      end
+
+      def resolve_metric_kpi_card(widget)
+        value_source = widget["value_source"]
+        label = widget_label(widget)
+
+        unless Metrics::PrometheusCheck.available?
+          return {
+            value: "\u2014",
+            label: label,
+            icon: widget["icon"],
+            tooltip: I18n.t("lcp_ruby.monitoring.prometheus_unavailable", default: "Prometheus client not available")
+          }
+        end
+
+        metric_name = value_source["name"]&.to_sym
+        metric = ::Prometheus::Client.registry.get(metric_name)
+        unless metric
+          return { value: "\u2014", label: label, icon: widget["icon"] }
+        end
+
+        label_filter = (value_source["labels"] || {}).transform_keys(&:to_sym)
+        value = read_metric_value(metric, label_filter)
+
+        {
+          value: value,
+          label: label,
+          icon: widget["icon"],
+          link_to: widget["link_to"],
+          format: widget["format"]
+        }
+      end
+
+      def read_metric_value(metric, label_filter)
+        metric.get(labels: label_filter.empty? ? {} : label_filter)
+      rescue KeyError, ArgumentError => e
+        Rails.logger.warn("[LcpRuby::Metrics] Failed to read metric: #{e.message}")
+        "\u2014"
+      end
+
+      def resolve_text(widget)
+        content_key = widget["content_key"]
+        {
+          content: I18n.t(content_key, default: content_key)
+        }
+      end
+
+      def resolve_list(widget)
+        ws = build_widget_scope(widget)
+        return { hidden: true } unless ws
+
+        limit = @zone.limit || 5
+        records = ws.scope.limit(limit).to_a
+
+        {
+          records: records,
+          model_name: widget["model"],
+          link_to: widget["link_to"]
+        }
+      end
+
+      VALID_CHART_TYPES = LcpRuby::Metadata::ZoneDefinition::VALID_CHART_TYPES
+      PIE_CHART_TYPES   = LcpRuby::Metadata::ZoneDefinition::PIE_CHART_TYPES
+      DEFAULT_CHART_LIBRARY = { responsive: true }.freeze
+
+      def resolve_chart(widget)
+        chart_type = widget["chart_type"]
+        unless VALID_CHART_TYPES.include?(chart_type)
+          return chart_defensive_fallback(widget,
+            "Chart widget has unknown chart_type '#{chart_type}'",
+            chart_type: chart_type)
+        end
+
+        ws = build_widget_scope(widget)
+        return { hidden: true } unless ws
+
+        chart_scope = ws.scope
+        chart_scope = apply_named_scope(chart_scope, ws.model_class, widget["scope"]) if widget["scope"]
+
+        series_configs = normalize_chart_series(widget)
+        series_data = series_configs.each_with_index.map do |s, i|
+          compute_series_data(ws, chart_scope, widget, s, i)
+        end
+
+        series_data = apply_zero_fill(series_data, widget)
+        sorted = apply_chart_sort(series_data, widget)
+
+        if sorted.all? { |s| s[:data].empty? }
+          return {
+            chart_type: chart_type,
+            empty: true,
+            message: chart_empty_message(widget),
+            label: widget_label(widget)
+          }
+        end
+
+        payload, options = assemble_chart_payload(chart_type, sorted, widget)
+
+        if PIE_CHART_TYPES.include?(chart_type) && payload.is_a?(Array)
+          return chart_defensive_fallback(widget,
+            "Pie/donut chart received array payload — multi-series with pie is invalid",
+            chart_type: chart_type)
+        end
+
+        {
+          chart_type: chart_type,
+          data: payload,
+          label: widget_label(widget),
+          link_to: widget["link_to"],
+          options: options
+        }
+      end
+
+      # Resolves model, evaluator, policy scope, soft-delete filter, and zone scope.
+      # Returns a WidgetScope or nil if the widget should be hidden.
+      def build_widget_scope(widget)
+        model_name = widget["model"]
+        return nil unless model_name
+
+        model_class = resolve_model_class(model_name)
+        return nil unless model_class
+
+        model_def = LcpRuby.loader.model_definition(model_name)
+        evaluator = build_evaluator(model_name)
+        return nil unless evaluator&.can?(:index)
+
+        base_scope = apply_policy_scope(model_class, evaluator)
+        base_scope = apply_soft_delete_filter(base_scope, model_def)
+        scope = apply_default_scope(base_scope, model_class)
+        scope = apply_zone_scope(scope, model_class)
+        scope = apply_filter_form(scope, model_class, @filter_form)
+        scope = apply_scope_filters(scope, model_class, @scope_filter_set)
+        scope = apply_scope_context(scope, model_class)
+
+        WidgetScope.new(model_class: model_class, model_def: model_def,
+                        evaluator: evaluator, base_scope: base_scope, scope: scope)
+      end
+
+      def normalize_chart_series(widget)
+        raw = widget["series"]
+        if raw.is_a?(Array) && raw.any?
+          raw
+        else
+          [ {} ]
+        end
+      end
+
+      def compute_series_data(ws, chart_scope, chart_widget, series, index)
+        effective_group_by = series["group_by"] || chart_widget["group_by"]
+        effective_period   = series["group_period"] || chart_widget["group_period"]
+        effective_agg      = (series["aggregate"] || chart_widget["aggregate"])&.to_sym
+        effective_field    = series["aggregate_field"] || chart_widget["aggregate_field"]
+
+        scope = chart_scope
+        scope = apply_named_scope(scope, ws.model_class, series["scope"]) if series["scope"]
+
+        grouped = DateGrouper.new(scope, field: effective_group_by, period: effective_period).group
+        data = compute_aggregate(grouped, effective_agg, effective_field)
+        data = translate_enum_keys(data, ws, effective_group_by) unless effective_period
+
+        {
+          name: resolve_series_name(series, index),
+          data: data,
+          color: resolve_series_color(series, chart_widget, index)
+        }
+      end
+
+      # Date-grouped charts skip this — the keys there are strftime
+      # buckets, not enum values, and need their own period-aware
+      # formatting (handled by Chartkick).
+      def translate_enum_keys(data, ws, group_by_field)
+        return data unless data.is_a?(Hash)
+        return data if group_by_field.blank? || ws.model_def.nil?
+
+        field_def = ws.model_def.field(group_by_field)
+        return data unless field_def&.enum?
+
+        data.transform_keys do |value|
+          Metadata::EnumLabelResolver.resolve(value, field_def, model_name: ws.model_def.name)
+        end
+      end
+
+      def resolve_series_name(series, index)
+        text = resolve_chart_text(series["name"], series["name_key"])
+        return text if text.present?
+        I18n.t("lcp_ruby.charts.series_default", default: "Series %{index}", index: index + 1)
+      end
+
+      def resolve_series_color(series, chart_widget, index)
+        return series["color"] if series["color"].present?
+        colors = chart_widget["colors"]
+        return colors[index] if colors.is_a?(Array) && colors[index].present?
+        ChartPalette.color_for(index)
+      end
+
+      # Pads each series with 0 for every missing period between
+      # min..max keys when `fill_zeros: true` is set with a uniform
+      # `group_period`. Without it Chartkick draws stacked-area / line
+      # charts with visible gaps wherever a series has no row.
+      #
+      # Bounded by ZERO_FILL_MAX_KEYS so a polluted dataset (stray
+      # 1970-01-01 row × daily period) can't OOM the renderer.
+      FILL_PERIODS = (DateGrouper::VALID_PERIODS - %w[week]).freeze
+      ZERO_FILL_MAX_KEYS = 5_000
+
+      def apply_zero_fill(series_data, widget)
+        return series_data unless widget["fill_zeros"] == true
+        return series_data if series_data.empty?
+
+        period = uniform_fill_period(widget) or return series_data
+        full_keys = enumerate_period_keys(series_data, period) or return series_data
+
+        series_data.map do |s|
+          padded = full_keys.each_with_object({}) { |k, h| h[k] = s[:data][k] || 0 }
+          s.merge(data: padded)
+        end
+      end
+
+      # Returns the single period shared by chart + all series, or nil
+      # when the page mixes periods (keys would live on different axes).
+      def uniform_fill_period(widget)
+        chart_period = widget["group_period"]
+        periods = (widget["series"] || []).map { |s| s["group_period"] || chart_period }.uniq
+        return nil if periods.size > 1
+        (periods.first || chart_period).presence
+      end
+
+      # Strftime'd or Date keys → chronological string sequence. Returns
+      # nil for periods we don't fill (week) or when the resulting span
+      # would exceed ZERO_FILL_MAX_KEYS.
+      def enumerate_period_keys(series_data, period)
+        return nil unless FILL_PERIODS.include?(period)
+
+        case period
+        when "quarter" then enumerate_quarter(series_data)
+        else
+          format = period_format(period)
+          dates  = parse_period_keys(series_data, format)
+          return nil if dates.empty?
+          enumerate_step(dates.min, dates.max, format, period)
+        end
+      end
+
+      def period_format(period)
+        case period
+        when "day"   then "%Y-%m-%d"
+        when "month" then "%Y-%m"
+        when "year"  then "%Y"
+        end
+      end
+
+      def parse_period_keys(series_data, format)
+        series_data.flat_map { |s| s[:data].keys }.uniq.filter_map do |k|
+          coerce_period_to_date(k, format)
+        end
+      end
+
+      def enumerate_step(min, max, format, period)
+        keys = []
+        cursor = min
+        while cursor <= max
+          keys << cursor.strftime(format)
+          return nil if keys.size > ZERO_FILL_MAX_KEYS
+          cursor = step_cursor(cursor, period)
+        end
+        keys
+      end
+
+      def step_cursor(date, period)
+        case period
+        when "day"   then date.next_day
+        when "month" then date.next_month
+        when "year"  then date.next_year
+        end
+      end
+
+      # SQLite emits "2024-Q1"; PostgreSQL DATE_TRUNC('quarter', …)
+      # emits a Date at the first day of the quarter — handle both.
+      def enumerate_quarter(series_data)
+        raw = series_data.flat_map { |s| s[:data].keys }.uniq
+        parsed = raw.filter_map { |k| parse_quarter(k) }
+        return nil if parsed.empty?
+
+        ordinal = ->(yq) { yq[0] * 4 + (yq[1] - 1) }
+        min, max = parsed.min_by(&ordinal), parsed.max_by(&ordinal)
+        keys = []
+        cursor = min
+        while ordinal.call(cursor) <= ordinal.call(max)
+          keys << "#{cursor[0]}-Q#{cursor[1]}"
+          return nil if keys.size > ZERO_FILL_MAX_KEYS
+          cursor = cursor[1] == 4 ? [ cursor[0] + 1, 1 ] : [ cursor[0], cursor[1] + 1 ]
+        end
+        keys
+      end
+
+      def parse_quarter(key)
+        case key
+        when Date, Time, DateTime
+          [ key.year, ((key.month - 1) / 3) + 1 ]
+        when String
+          (m = key.match(/\A(\d{4})-Q([1-4])\z/)) && [ m[1].to_i, m[2].to_i ]
+        end
+      end
+
+      def coerce_period_to_date(key, format)
+        case key
+        when Date     then key
+        when Time, DateTime then key.to_date
+        when String   then Date.strptime(key, format)
+        end
+      rescue ArgumentError
+        nil
+      end
+
+      def apply_chart_sort(series_data, widget)
+        sort_mode = widget["sort"] || default_chart_sort(widget)
+        return series_data if sort_mode == "none"
+
+        case sort_mode
+        when "asc"
+          series_data.map { |s| s.merge(data: s[:data].sort.to_h) }
+        when "desc"
+          series_data.map { |s| s.merge(data: s[:data].sort.reverse.to_h) }
+        when "value_asc", "value_desc"
+          sums = Hash.new(0)
+          series_data.each { |s| s[:data].each { |k, v| sums[k] += v.to_f } }
+          ordered_keys = sums.sort_by { |_k, v| v }.map(&:first)
+          ordered_keys.reverse! if sort_mode == "value_desc"
+          series_data.map do |s|
+            reordered = ordered_keys.each_with_object({}) { |k, h| h[k] = s[:data][k] if s[:data].key?(k) }
+            s.merge(data: reordered)
+          end
+        else
+          series_data
+        end
+      end
+
+      def default_chart_sort(widget)
+        widget["group_period"] ? "asc" : "none"
+      end
+
+      def assemble_chart_payload(chart_type, series_data, widget)
+        options = assemble_chart_options(chart_type, widget, series_data.size)
+
+        if PIE_CHART_TYPES.include?(chart_type)
+          payload = series_data.first&.dig(:data) || {}
+          options[:colors] = widget["colors"] if widget["colors"].is_a?(Array)
+          [ payload, options ]
+        else
+          payload = series_data.map do |s|
+            row = { name: s[:name], data: s[:data] }
+            row[:color] = s[:color] if s[:color]
+            row
+          end
+          [ payload, options ]
+        end
+      end
+
+      def assemble_chart_options(chart_type, widget, series_count)
+        options = {}
+
+        legend = resolve_chart_legend(widget["legend"], chart_type, series_count)
+        options[:legend] = legend unless legend.nil?
+
+        unless PIE_CHART_TYPES.include?(chart_type)
+          options[:stacked] = true if widget["stacked"] == true
+          copy_chart_option(options, widget, "min", :min)
+          copy_chart_option(options, widget, "max", :max)
+
+          xtitle = resolve_chart_text(widget["xtitle"], widget["xtitle_key"])
+          options[:xtitle] = xtitle if xtitle.present?
+
+          ytitle = resolve_chart_text(widget["ytitle"], widget["ytitle_key"])
+          options[:ytitle] = ytitle if ytitle.present?
+
+          if %w[line area].include?(chart_type)
+            copy_chart_option(options, widget, "points", :points)
+            copy_chart_option(options, widget, "curve", :curve)
+            copy_chart_option(options, widget, "discrete", :discrete)
+          end
+        end
+
+        copy_chart_option(options, widget, "prefix",    :prefix)
+        copy_chart_option(options, widget, "suffix",    :suffix)
+        copy_chart_option(options, widget, "precision", :precision)
+        copy_chart_option(options, widget, "thousands", :thousands)
+        options[:download] = true if widget["download"] == true
+        copy_chart_option(options, widget, "height", :height)
+
+        user_lib = (widget["library"] || {}).deep_symbolize_keys
+        options[:library] = DEFAULT_CHART_LIBRARY.deep_merge(user_lib)
+
+        options
+      end
+
+      # Forward a widget option to Chartkick when explicitly set.
+      # Distinguishes "not set" (nil / key absent) from valid falsy/zero values
+      # such as `min: 0`, `precision: 0`, or `points: false`.
+      def copy_chart_option(options, widget, key, target)
+        return unless widget.key?(key)
+        value = widget[key]
+        return if value.nil?
+        options[target] = value
+      end
+
+      def resolve_chart_legend(legend, chart_type, series_count)
+        return legend if legend == true || legend == false
+        return legend if legend.is_a?(String) && legend != "auto"
+        # auto or nil → context-aware
+        if PIE_CHART_TYPES.include?(chart_type)
+          true
+        elsif series_count > 1
+          true
+        else
+          false
+        end
+      end
+
+      def resolve_chart_text(literal, key)
+        Metadata::I18nLabel.resolve(
+          literal: literal, key: key,
+          fallback: key.present? ? humanize_i18n_key(key) : nil
+        )
+      end
+
+      def humanize_i18n_key(key)
+        key.to_s.split(".").last.to_s.humanize
+      end
+
+      def chart_empty_message(widget)
+        resolve_chart_text(widget["empty"], widget["empty_key"]) ||
+          I18n.t("lcp_ruby.charts.no_data", default: "No data for the selected period.")
+      end
+
+      def chart_defensive_fallback(widget, message, chart_type: nil)
+        err = LcpRuby::Error.new(message)
+        raise err unless Rails.env.production?
+        LcpRuby.record_error(err, subsystem: "widgets",
+                             model: widget["model"], chart_type: chart_type)
+        {
+          chart_type: nil,
+          error: true,
+          message: I18n.t("lcp_ruby.charts.error", default: "Chart could not be rendered."),
+          label: widget_label(widget)
+        }
+      end
+
+      def compute_comparison(ws, widget)
+        compare_scope_name = widget["compare_scope"]
+        unless ws.model_class.respond_to?(compare_scope_name)
+          Rails.logger.warn("[LcpRuby::Widgets] compare_scope '#{compare_scope_name}' " \
+                            "not found on model '#{widget["model"]}'")
+          return nil
+        end
+        scope = ws.base_scope.public_send(compare_scope_name)
+        compute_aggregate(scope, widget["aggregate"]&.to_sym, widget["aggregate_field"])
+      end
+
+      def trend_data(current, previous)
+        return {} if current.nil? || previous.nil?
+
+        direction = resolve_trend_direction(current, previous)
+        change_pct = compute_change_pct(current, previous)
+
+        { trend_direction: direction, trend_change_pct: change_pct, trend_previous: previous }
+      end
+
+      def resolve_trend_direction(current, previous)
+        if current > previous
+          :up
+        elsif current < previous
+          :down
+        else
+          :neutral
+        end
+      end
+
+      def compute_change_pct(current, previous)
+        if previous.zero?
+          current.zero? ? 0.0 : nil
+        else
+          ((current - previous).to_f / previous * 100).round(1)
+        end
+      end
+
+      def compute_aggregate(scope, aggregate, field)
+        case aggregate
+        when :count then scope.count
+        when :sum   then scope.sum(field || :id)
+        when :avg
+          result = scope.average(field || :id)
+          # Grouped queries return { group_value => avg }; non-grouped returns a
+          # single scalar. Coerce BigDecimal → Float in both shapes so Chartkick
+          # tooltips render numbers, not BigDecimal#to_s.
+          result.is_a?(Hash) ? result.transform_values { |v| v&.to_f } : result&.to_f
+        when :min   then scope.minimum(field || :id)
+        when :max   then scope.maximum(field || :id)
+        else scope.count
+        end
+      end
+
+      def resolve_embed(widget)
+        provider_name = widget["provider"]
+        provider = LcpRuby.configuration.embed_provider(provider_name)
+        unless provider
+          Rails.logger.warn("[LcpRuby::Widgets] Embed provider '#{provider_name}' not configured")
+          return { hidden: true }
+        end
+
+        url = provider.embed_url(
+          resource_type: widget["resource_type"],
+          resource_id: widget["resource_id"],
+          params: widget["params"] || {},
+          user: @user
+        )
+
+        {
+          embed_url: url,
+          height: widget["height"] || "400px",
+          label: widget_label(widget)
+        }
+      end
+
+      def resolve_workflow_graph(widget)
+        return { hidden: true } unless Workflow::Registry.available?
+
+        model_name = widget["model"]
+        workflow = if model_name
+          Workflow::Registry.workflow_for_model(model_name)
+        end
+        return { hidden: true } unless workflow
+
+        current_state = @record&.respond_to?(workflow.field) ? @record.send(workflow.field)&.to_s : nil
+
+        builder_options = {
+          "direction" => widget.fetch("direction", "LR"),
+          "show_transition_labels" => widget.fetch("show_transition_labels", true),
+          "show_roles" => widget.fetch("show_roles", false),
+          "show_guards" => widget.fetch("show_guards", false),
+          "collapse_universal" => widget.fetch("collapse_universal", true)
+        }
+
+        # Audit trail overlay
+        if widget["show_audit_trail"] && @record && workflow.audit_log && Workflow::AuditRegistry.available?
+          builder_options["audit_trail"] = load_audit_trail(workflow)
+        end
+
+        # Available transitions highlight (filtered by role + guard for current user)
+        if widget["highlight_available"] && current_state && @record
+          evaluator = build_evaluator(workflow.model)
+          if evaluator
+            state_machine = Workflow::StateMachine.new(workflow)
+            available = state_machine.available_transitions(@record, user: @user, evaluator: evaluator)
+            builder_options["available_transitions"] = available
+          end
+        end
+
+        builder = Workflow::MermaidBuilder.new(workflow, current_state: current_state, options: builder_options)
+        mermaid_code_light, mermaid_code_dark = builder.build_for_palettes(:light, :dark)
+
+        {
+          mermaid_code: mermaid_code_light,
+          mermaid_code_dark: mermaid_code_dark,
+          workflow_name: workflow.name,
+          current_state: current_state,
+          direction: builder_options["direction"],
+          label: widget_label(widget)
+        }
+      end
+
+      def load_audit_trail(workflow)
+        audit_model = Workflow::AuditRegistry.audit_model_class
+        return nil unless audit_model
+
+        fields = Workflow::AuditWriter.field_mapping
+        from_key = fields["from_state"]
+        to_key = fields["to_state"]
+
+        logs = audit_model.where(
+          fields["record_type"] => @record.class.name.demodulize.underscore,
+          fields["record_id"] => @record.id,
+          fields["workflow_name"] => workflow.name
+        ).order(:created_at)
+
+        logs.map do |log|
+          { from_state: log.send(from_key), to_state: log.send(to_key) }
+        end
+      rescue LcpRuby::Error, ActiveRecord::StatementInvalid => e
+        raise unless Rails.env.production?
+
+        Rails.logger.error("[LcpRuby::Widgets] Could not load audit trail for " \
+                           "#{@record.class.name}##{@record.id}: #{e.message}")
+        nil
+      end
+
+      def resolve_approval_status
+        return { hidden: true } unless @record
+        return { hidden: true } unless Workflow::Approval::Registry.available?
+
+        data = Workflow::Approval::DataBuilder.build(record: @record, user: @user)
+        return { hidden: true } unless data
+
+        data
+      end
+
+      def widget_label(widget)
+        text = resolve_chart_text(widget["label"], widget["label_key"])
+        return text if text.present?
+        @zone.name.humanize
+      end
+    end
+  end
+end