lcp 0.1.0

data/lib/lcp_ruby/presenter/column_set.rb

@@ -0,0 +1,268 @@
+module LcpRuby
+  module Presenter
+    class ColumnSet
+      include MetadataLookup
+
+      attr_reader :presenter_definition, :permission_evaluator
+
+      def initialize(presenter_definition, permission_evaluator)
+        @presenter_definition = presenter_definition
+        @permission_evaluator = permission_evaluator
+      end
+
+      def visible_table_columns
+        @visible_table_columns ||= compute_visible_table_columns
+      end
+
+      def visible_form_fields(section_fields)
+        writable = permission_evaluator.writable_fields
+
+        section_fields.select do |field|
+          if field["custom_field"]
+            permission_evaluator.field_writable?(field["field"])
+          else
+            writable.include?(field["field"])
+          end
+        end
+      end
+
+      def visible_show_fields(section_fields)
+        readable = permission_evaluator.readable_fields
+
+        section_fields.select do |field|
+          if field["custom_field"]
+            permission_evaluator.field_readable?(field["field"])
+          else
+            field_visible?(field["field"], readable)
+          end
+        end
+      end
+
+      # Filter card fields by readable permissions. Returns array of field config hashes.
+      # Used by all card-based layouts (tiles, kanban, future).
+      def visible_card_fields(card_config)
+        readable = permission_evaluator.readable_fields
+        fields = card_config["fields"] || []
+
+        fields.select do |field_config|
+          field_visible?(field_config["field"], readable)
+        end
+      end
+
+      # Returns true when the current user can read the named-slot field.
+      # Field-level permissions in LCP are model+role+field scoped (class-level), so the
+      # check needs no record. Per-record visibility is already handled by policy_scope
+      # before any card is rendered. Dot-paths and template strings are skipped here —
+      # the resolver enforces field_readable? at every traversal step.
+      def readable_named_slot?(field_name)
+        return true if field_name.blank?
+        return true if FieldValueResolver.dot_path?(field_name) ||
+                       FieldValueResolver.template_field?(field_name)
+
+        permission_evaluator.field_readable?(field_name.to_s)
+      end
+
+      # Build a mapping from FK field name to the belongs_to AssociationDefinition,
+      # filtered to only include FK fields the current user has permission to see.
+      # Returns a Hash: { "company_id" => AssociationDefinition, ... }
+      # Used by the index view to resolve associated objects instead of showing raw FK integers.
+      def fk_association_map(model_definition)
+        visible_fields = visible_table_columns.map { |c| c["field"] }
+        model_definition.belongs_to_fk_map.select { |k, _| visible_fields.include?(k) }
+      end
+
+      private
+
+      def compute_visible_table_columns
+        all_columns = presenter_definition.table_columns
+        readable = permission_evaluator.readable_fields
+
+        result = all_columns.select do |col|
+          next true if col["aggregate"]
+          next true if presenter_definition.grouped_query?
+
+          field_visible?(col["field"], readable)
+        end
+
+        result = inject_workflow_badge_renderers(result)
+        result = enrich_renderer_for_type(result) if LcpRuby.configuration.runtime_type_renderers
+        result = enrich_link_options_on_columns(result) unless presenter_definition.grouped_query?
+
+        return result if presenter_definition.grouped_query?
+
+        append_custom_table_columns(result, readable)
+      end
+
+      # Phase 4 of type-system defaults — Decision 14. When the
+      # `runtime_type_renderers` flag is on, fills in `col["renderer"]` from
+      # the field type's default renderer (`Types::TypeRegistry.renderer_for`)
+      # for any column whose renderer is blank. So `column :flag` on a
+      # :boolean field renders as boolean_icon (✓/✗) and `column :status`
+      # on an :enum field renders as a badge — without the configurator
+      # writing renderer: explicitly.
+      #
+      # Idempotent: skips columns that already have a renderer (mirrors
+      # `inject_workflow_badge_renderers`'s `next col if col.key?("renderer")`
+      # guard pattern at column_set.rb:108-124). Skips dot-path / template
+      # / aggregate / custom-field columns where the field-by-name lookup
+      # would fail or be inappropriate.
+      def enrich_renderer_for_type(columns)
+        model_def = load_model_definition(presenter_definition.model)
+        return columns unless model_def
+
+        columns.map do |col|
+          next col unless col.is_a?(Hash)
+          next col if col["renderer"].present?
+          next col if col["partial"].present?
+          next col if col["aggregate"]
+          next col if col["custom_field"]
+
+          field_name = col["field"].to_s
+          next col if field_name.empty?
+          next col if Presenter::FieldValueResolver.dot_path?(field_name)
+          next col if Presenter::FieldValueResolver.template_field?(field_name)
+
+          field = model_def.field(field_name)
+          next col unless field
+
+          type_renderer = Types::TypeRegistry.renderer_for(field.type)
+          next col unless type_renderer
+
+          col.merge("renderer" => type_renderer)
+        end
+      end
+
+      def enrich_link_options_on_columns(columns)
+        model_def = load_model_definition(presenter_definition.model)
+        return columns unless model_def
+
+        columns.map do |col|
+          next col unless col.is_a?(Hash)
+
+          Presenter::Enrichment.enrich(col, location: :column, model_def: model_def, loader: LcpRuby.loader)
+        end
+      end
+
+      # Injects workflow_badge renderer for the workflow field on index columns.
+      # No enum type check needed — workflow field is always enum (validated at boot).
+      def inject_workflow_badge_renderers(columns)
+        return columns unless Workflow::Registry.available?
+
+        model_name = presenter_definition.model
+        workflow = Workflow::Registry.workflow_for_model(model_name)
+        return columns unless workflow
+
+        columns.map do |col|
+          next col if col.key?("renderer")
+          next col unless col["field"] == workflow.field
+
+          col.merge(
+            "renderer" => "workflow_badge",
+            "options" => (col["options"] || {}).merge("_model_name" => model_name)
+          )
+        end
+      end
+
+      def append_custom_table_columns(columns, readable)
+        model_name = presenter_definition.model
+        model_def = load_model_definition(model_name)
+        return columns unless model_def&.custom_fields_enabled?
+
+        definitions = CustomFields::Registry.for_model(model_name)
+        definitions.select { |d| d.active && d.show_in_table }.each do |defn|
+          next unless permission_evaluator.field_readable?(defn.field_name)
+
+          columns << {
+            "field" => defn.field_name,
+            "label" => defn.label,
+            "sortable" => defn.sortable,
+            "custom_field" => true,
+            "width" => defn.column_width
+          }.compact
+        end
+
+        columns
+      rescue LcpRuby::Error
+        columns
+      end
+
+      def field_visible?(field_path, readable)
+        field_path = field_path.to_s
+
+        if FieldValueResolver.template_field?(field_path)
+          template_field_visible?(field_path, readable)
+        elsif FieldValueResolver.dot_path?(field_path)
+          dot_path_field_visible?(field_path)
+        elsif virtual_column_field?(field_path)
+          true # Virtual columns visible to all roles (per spec Decision #5)
+        elsif (assoc = belongs_to_association(presenter_definition.model, field_path))
+          # Plain belongs_to field: visible iff the FK itself is readable
+          # (mirrors the dot-path terminal-belongs_to rule below).
+          readable.include?(assoc.foreign_key)
+        else
+          readable.include?(field_path)
+        end
+      end
+
+      def template_field_visible?(template, readable)
+        refs = template.scan(/\{([^}]+)\}/).flatten.map(&:strip)
+        refs.all? do |ref|
+          if FieldValueResolver.dot_path?(ref)
+            dot_path_field_visible?(ref)
+          else
+            readable.include?(ref)
+          end
+        end
+      end
+
+      def dot_path_field_visible?(field_path)
+        parts = field_path.split(".")
+        model_name = presenter_definition.model
+
+        current_model_def = load_model_definition(model_name)
+        return false unless current_model_def
+
+        parts.each_with_index do |part, index|
+          if index == parts.length - 1
+            # Terminal segment may itself be a belongs_to association
+            # (e.g. "manager.organizational_unit" → link-through target).
+            if (terminal_assoc = belongs_to_association(current_model_def.name, part))
+              evaluator = build_evaluator_for(current_model_def.name)
+              return evaluator.field_readable?(terminal_assoc.foreign_key)
+            end
+
+            # Terminal field: check readability on current model
+            evaluator = build_evaluator_for(current_model_def.name)
+            return evaluator.field_readable?(part)
+          else
+            # Association segment: find and traverse
+            assoc = current_model_def.associations.find { |a| a.name == part }
+            return false unless assoc
+
+            # Non-LCP targets have no per-field metadata permissions, so any
+            # remaining field on them is visible to whoever can see the presenter.
+            return true unless assoc.lcp_model?
+
+            current_model_def = load_model_definition(assoc.target_model)
+            return false unless current_model_def
+          end
+        end
+
+        false
+      end
+
+      def virtual_column_field?(field_path)
+        model_def = load_model_definition(presenter_definition.model)
+        model_def&.virtual_column(field_path).present?
+      end
+
+      def belongs_to_association(model_name, name)
+        load_model_definition(model_name)&.find_belongs_to(name)
+      end
+
+      def root_model_name
+        presenter_definition.model
+      end
+    end
+  end
+end

data/lib/lcp_ruby/presenter/enrichment.rb

@@ -0,0 +1,136 @@
+module LcpRuby
+  module Presenter
+    # Per-entry decoration of show fields and index columns.
+    # Each enricher is a pure function: (entry, location:, model_def:, loader:) -> entry.
+    # Must be a no-op when the enricher's keys are absent from entry.
+    module Enrichment
+      ENTRY_ENRICHERS = %i[link].freeze
+
+      module_function
+
+      # Decorate a single field/column hash with enricher-produced keys.
+      #
+      # @param entry [Hash] field or column config hash (string keys)
+      # @param location [Symbol] :field (show) or :column (index)
+      # @param model_def [Metadata::ModelDefinition] owner model of the entry
+      # @param loader [Metadata::Loader] current loader (for presenter / target-model lookup)
+      # @return [Hash] entry with any enricher keys merged in
+      def enrich(entry, location:, model_def:, loader:)
+        return entry unless entry.is_a?(Hash)
+
+        ENTRY_ENRICHERS.reduce(entry) do |e, name|
+          send("enrich_#{name}_options", e, location: location, model_def: model_def, loader: loader)
+        end
+      end
+
+      # Silent on invalid input — the boot-time validator rejects it first.
+      def enrich_link_options(entry, location:, model_def:, loader:)
+        return entry unless link_opt_in?(entry, location)
+
+        chain, target_model = resolve_chain(entry, location: location, model_def: model_def, loader: loader)
+        return entry if chain.nil?
+
+        slug = resolve_presenter_slug(target_model, entry: entry)
+
+        entry.merge(
+          "link_chain" => chain,
+          "link_target_model" => target_model,
+          "link_target_presenter_slug" => slug
+        )
+      end
+
+      def link_opt_in?(entry, location)
+        return true if entry["link"] == true
+        return true if entry["link_through"].present?
+        return true if location == :column && entry["link_to"].to_s == "show"
+
+        false
+      end
+
+      # Returns [chain_array, target_model_name] or [nil, nil] when enrichment should be skipped.
+      def resolve_chain(entry, location:, model_def:, loader:)
+        # Explicit link_through takes precedence over auto-detection.
+        lt = entry["link_through"]
+        if lt.present?
+          assoc = model_def.find_belongs_to(lt.to_s)
+          return [ nil, nil ] unless assoc&.target_model
+
+          return [ [ lt.to_s ], assoc.target_model ]
+        end
+
+        field = entry["field"].to_s
+
+        # Column: link_to: :show and link:true on scalar → empty chain (current row).
+        if location == :column
+          if entry["link_to"].to_s == "show" || (entry["link"] == true && !field.include?(".") && model_def.find_belongs_to(field).nil?)
+            return [ [], model_def.name ]
+          end
+        end
+
+        # From here on, only link: true remains (explicit link_through was handled above).
+        return [ nil, nil ] unless entry["link"] == true
+
+        if field.include?(".")
+          auto_detect_dot_path(field, model_def: model_def, loader: loader)
+        elsif (assoc = model_def.find_belongs_to(field))
+          [ [ field ], assoc.target_model ]
+        else
+          [ nil, nil ] # show-field link:true on scalar — validator V3a errors
+        end
+      end
+
+      # Walk a dot-path and compute (chain, target_model).
+      # Chain = every segment except a scalar terminal; if the terminal is itself a belongs_to,
+      # the whole path is the chain.
+      def auto_detect_dot_path(field, model_def:, loader:)
+        segments = field.split(".")
+        current_model = model_def
+
+        segments[0..-2].each do |seg|
+          assoc = current_model.find_belongs_to(seg)
+          return [ nil, nil ] unless assoc&.target_model
+
+          next_def = loader.model_definitions[assoc.target_model]
+          return [ nil, nil ] unless next_def
+
+          current_model = next_def
+        end
+
+        last = segments.last
+        terminal = current_model.find_belongs_to(last)
+
+        if terminal
+          return [ nil, nil ] if terminal.polymorphic || terminal.target_model.nil?
+
+          [ segments, terminal.target_model ]
+        else
+          [ segments[0..-2], current_model.name ]
+        end
+      end
+
+      # B19 — three-tier resolution for multi-presenter models:
+      #   1. Per-link override (`link_presenter:` on entry) wins when present.
+      #   2. Single presenter — unambiguous, backward-compatible (most models).
+      #   3. Multi-presenter — the one marked `default: true` is canonical.
+      #
+      # Returns nil when multi-presenter has no resolution; the validator
+      # rejects that configuration at boot, so we don't have to fall back
+      # to alphabetic order at render time (which was the original B19 bug).
+      def resolve_presenter_slug(target_model_name, entry: nil)
+        return nil if target_model_name.blank?
+
+        presenters = Resolver.presenters_for_model(target_model_name)
+
+        if entry && (override = entry["link_presenter"]).present?
+          return presenters.find { |p| p.slug == override.to_s }&.slug
+        end
+
+        return presenters.first&.slug if presenters.length <= 1
+
+        presenters.find(&:default?)&.slug
+      rescue MetadataError
+        nil
+      end
+    end
+  end
+end

data/lib/lcp_ruby/presenter/field_value_resolver.rb

@@ -0,0 +1,237 @@
+module LcpRuby
+  module Presenter
+    class FieldValueResolver
+      include MetadataLookup
+
+      attr_reader :model_definition, :permission_evaluator
+
+      def initialize(model_definition, permission_evaluator)
+        @model_definition = model_definition
+        @permission_evaluator = permission_evaluator
+      end
+
+      # Resolve a field value from a record using various path types.
+      #
+      # @param record [ActiveRecord::Base] the record to resolve from
+      # @param field_path [String] field name, dot-path, or template
+      # @param fk_map [Hash] FK field name => AssociationDefinition (for backward compat)
+      # @param raw [Boolean] when true, return raw enum keys instead of i18n
+      #   labels (used by raw `.json` / `.csv` endpoints).
+      # @return [Object, nil] resolved value
+      def resolve(record, field_path, fk_map: {}, raw: false)
+        field_path = field_path.to_s
+        return nil if field_path.blank?
+
+        if self.class.template_field?(field_path)
+          resolve_template(record, field_path, fk_map: fk_map)
+        elsif self.class.dot_path?(field_path)
+          resolve_dot_path(record, field_path, raw: raw)
+        elsif virtual_column_field?(field_path)
+          resolve_virtual_column(record, field_path)
+        elsif fk_map.key?(field_path)
+          resolve_fk(record, fk_map[field_path])
+        elsif (assoc = model_definition.find_belongs_to(field_path))
+          resolve_association_record(record, assoc.name)
+        else
+          resolve_simple(record, field_path, raw: raw)
+        end
+      end
+
+      def self.dot_path?(field)
+        field.to_s.include?(".") && !field.to_s.include?("{")
+      end
+
+      def self.template_field?(field)
+        field.to_s.include?("{") && field.to_s.include?("}")
+      end
+
+      # Coerce an associated record to a display string. Callers that get back
+      # an AR instance (FK resolution, terminal-belongs_to dot-path, plain
+      # belongs_to field) run through this to get a human-readable label.
+      def self.association_label(record)
+        return nil if record.nil?
+
+        record.respond_to?(:to_label) ? record.to_label : record.to_s
+      end
+
+      private
+
+      def root_model_name
+        model_definition.name
+      end
+
+      def resolve_template(record, template, fk_map: {})
+        template.gsub(/\{([^}]+)\}/) do |_match|
+          ref = Regexp.last_match(1).strip
+          resolve_ref(record, ref, fk_map: fk_map).to_s
+        end
+      end
+
+      def resolve_ref(record, ref, fk_map: {})
+        if self.class.dot_path?(ref)
+          resolve_dot_path(record, ref)
+        elsif fk_map.key?(ref)
+          resolve_fk(record, fk_map[ref])
+        else
+          resolve_simple(record, ref)
+        end
+      end
+
+      def resolve_dot_path(record, field_path, raw: false)
+        parts = field_path.split(".")
+
+        # Custom fields use dot-path notation (custom_fields.nickname) but are not associations —
+        # the field name is a dynamic accessor on the record itself.
+        if parts.first == "custom_fields" && parts.length == 2
+          return resolve_simple(record, parts.last, raw: raw)
+        end
+
+        current_record = record
+        current_model_def = model_definition
+
+        parts.each_with_index do |part, index|
+          last_segment = (index == parts.length - 1)
+
+          if last_segment
+            # Terminal belongs_to: return the record itself so the view can
+            # render a label / wrap it in a link (not the FK scalar).
+            if (terminal_assoc = current_model_def.find_belongs_to(part))
+              return nil if current_record.nil?
+              return nil unless terminal_assoc.target_model
+
+              return resolve_association_record(current_record, terminal_assoc.name)
+            end
+
+            # Terminal field — check permission on current model and read value
+            return read_terminal_value(current_record, part, current_model_def, raw: raw)
+          else
+            # Association traversal
+            assoc = current_model_def.associations.find { |a| a.name == part }
+            return nil unless assoc
+
+            # Non-LCP targets (e.g. userstamp → User) have no metadata, so we
+            # can't run permission checks; fall back to plain public_send.
+            unless assoc.lcp_model?
+              return nil unless assoc.singular?
+
+              return resolve_non_lcp_tail(current_record, part, parts[(index + 1)..])
+            end
+
+            # Permission check: the association name must be traversable
+            # (we check readability of the final field on the target model)
+            next_model_def = load_model_definition(assoc.target_model)
+            return nil unless next_model_def
+
+            if assoc.type == "has_many"
+              # For has_many, resolve the remaining path on each related record
+              return resolve_has_many(current_record, part, parts[(index + 1)..], next_model_def, raw: raw)
+            end
+
+            # belongs_to / has_one — traverse
+            current_record = current_record.respond_to?(part) ? current_record.public_send(part) : nil
+            return nil if current_record.nil?
+            current_model_def = next_model_def
+          end
+        end
+      end
+
+      def resolve_non_lcp_tail(record, assoc_name, remaining_parts)
+        current = record.respond_to?(assoc_name) ? record.public_send(assoc_name) : nil
+        return nil if current.nil?
+
+        remaining_parts.each do |part|
+          current = current.respond_to?(part) ? current.public_send(part) : nil
+          return nil if current.nil?
+        end
+
+        current
+      end
+
+      def resolve_has_many(record, assoc_name, remaining_parts, target_model_def, raw: false)
+        return nil unless record.respond_to?(assoc_name)
+
+        related = record.public_send(assoc_name)
+        return [] unless related.respond_to?(:map)
+
+        remaining_path = remaining_parts.join(".")
+
+        related.map do |related_record|
+          sub_resolver = self.class.new(target_model_def, build_evaluator_for(target_model_def.name))
+          sub_resolver.resolve(related_record, remaining_path, raw: raw)
+        end.compact
+      end
+
+      def read_terminal_value(record, field_name, current_model_def, raw: false)
+        return nil if record.nil?
+
+        evaluator = build_evaluator_for(current_model_def.name)
+        return nil unless evaluator.field_readable?(field_name)
+
+        value = record.respond_to?(field_name) ? record.public_send(field_name) : nil
+        return value if raw
+
+        Metadata::EnumLabelResolver.resolve(value, lookup_field(current_model_def, field_name),
+                                            model_name: current_model_def.name)
+      end
+
+      def resolve_fk(record, assoc)
+        return nil unless record.respond_to?(assoc.name)
+
+        self.class.association_label(record.public_send(assoc.name))
+      end
+
+      def resolve_simple(record, field_name, raw: false)
+        value = record.respond_to?(field_name) ? record.public_send(field_name) : nil
+        return value if raw
+
+        # `lookup_field` returns nil for unregistered names (e.g., custom
+        # fields), letting EnumLabelResolver pass them through unchanged.
+        Metadata::EnumLabelResolver.resolve(value, lookup_field(model_definition, field_name),
+                                            model_name: model_definition.name)
+      end
+
+      # Memoizes `ModelDefinition#field` (O(n) on `fields`) per resolver
+      # instance — index/show pages render the same field across many rows,
+      # which would otherwise repeat the linear scan ~rows × columns times.
+      # Stores nil hits explicitly so unregistered names (e.g., custom
+      # fields) don't re-scan.
+      def lookup_field(model_def, field_name)
+        @field_cache ||= {}
+        key = [ model_def.name, field_name ]
+        return @field_cache[key] if @field_cache.key?(key)
+
+        @field_cache[key] = model_def.field(field_name)
+      end
+
+      # Returns the associated record object (not a label) so callers can apply
+      # a renderer/partial, fall back to association_label, or wrap in a link.
+      def resolve_association_record(record, assoc_name)
+        return nil unless record.respond_to?(assoc_name)
+
+        record.public_send(assoc_name)
+      end
+
+      def virtual_column_field?(field_path)
+        model_definition.virtual_column(field_path).present?
+      end
+
+      def resolve_virtual_column(record, name)
+        value = if record.respond_to?(name)
+          record.public_send(name)
+        elsif record.respond_to?(:read_attribute)
+          record.read_attribute(name)
+        end
+
+        # Loaded-tracking guard: if nil on a persisted record, check if the VC
+        # was actually in the query's SELECT. Prevents silent nil from missing VCs.
+        if value.nil? && record.respond_to?(:virtual_column_loaded?) && !record.virtual_column_loaded?(name)
+          raise LcpRuby::Error,
+            "virtual column '#{name}' not loaded in query SELECT — " \
+            "add it to presenter virtual_columns or check VirtualColumns::Collector detection"
+        end
+
+        value
+      end
+    end
+  end
+end

data/lib/lcp_ruby/presenter/includes_resolver/association_dependency.rb

@@ -0,0 +1,59 @@
+module LcpRuby
+  module Presenter
+    module IncludesResolver
+      # Value object representing a single association that needs eager loading.
+      #
+      # @param path [Symbol, Hash] Association path in Rails includes format
+      #   e.g. :company or { company: :industry }
+      # @param reason [:display, :query]
+      #   :display — need associated objects for rendering (to_label, association_list)
+      #   :query   — need the table JOINed for WHERE/ORDER BY
+      class AssociationDependency
+        VALID_REASONS = %i[display query].freeze
+
+        attr_reader :path, :reason
+
+        def initialize(path:, reason:)
+          @path = path
+          @reason = reason.to_sym
+
+          validate!
+        end
+
+        # Top-level association name regardless of nesting.
+        # :company from either :company or { company: :industry }
+        def association_name
+          case path
+          when Symbol then path
+          when Hash   then path.keys.first
+          else raise ArgumentError, "Invalid path type: #{path.class}"
+          end
+        end
+
+        def nested?
+          path.is_a?(Hash)
+        end
+
+        def query?
+          reason == :query
+        end
+
+        def display?
+          reason == :display
+        end
+
+        private
+
+        def validate!
+          unless path.is_a?(Symbol) || path.is_a?(Hash)
+            raise ArgumentError, "path must be a Symbol or Hash, got #{path.class}"
+          end
+
+          unless VALID_REASONS.include?(reason)
+            raise ArgumentError, "reason must be one of #{VALID_REASONS}, got #{reason.inspect}"
+          end
+        end
+      end
+    end
+  end
+end