lcp 0.1.0

data/lib/lcp_ruby/metadata/model_definition.rb

@@ -0,0 +1,612 @@
+module LcpRuby
+  module Metadata
+    class ModelDefinition
+      attr_reader :name, :label, :label_plural, :table_name, :fields,
+                  :validations, :associations, :scopes, :events, :options,
+                  :display_templates, :virtual_columns, :indexes, :raw_hash, :data_source_config,
+                  :source_path, :source_type, :abstract, :inherits, :sti_child,
+                  :bind_to, :bind_to_apply, :slug_field,
+                  :label_source_loc, :label_plural_source_loc
+      attr_writer :source_path, :source_type, :table_name
+      attr_accessor :positioning_config
+
+      # Backward compatibility alias
+      alias_method :aggregates, :virtual_columns
+
+      def initialize(attrs = {})
+        @name = attrs[:name].to_s
+        @label = attrs[:label] || @name.humanize
+        @label_plural = attrs[:label_plural] || @label.pluralize
+        @table_name = attrs[:table_name] || @name.pluralize
+        @fields = attrs[:fields] || []
+        @validations = attrs[:validations] || []
+        @associations = attrs[:associations] || []
+        @scopes = attrs[:scopes] || []
+        @events = attrs[:events] || []
+        @options = attrs[:options] || {}
+        @display_templates = attrs[:display_templates] || {}
+        @virtual_columns = attrs[:virtual_columns] || attrs[:aggregates] || {}
+        @indexes = attrs[:indexes] || []
+        @positioning_config = attrs[:positioning_config]
+        @data_source_config = attrs[:data_source_config]
+        @raw_hash = attrs[:raw_hash]
+        @source_path = attrs[:source_path]
+        @source_type = attrs[:source_type]
+        @abstract = attrs.fetch(:abstract, false)
+        @inherits = attrs[:inherits]
+        @sti_child = attrs.fetch(:sti_child, false)
+        @bind_to = attrs[:bind_to]
+        @bind_to_apply = attrs[:bind_to_apply] || []
+        @slug_field = attrs[:slug_field]&.to_s.presence
+        # i18n_check Phase 3a façade source-location capture. Set by
+        # ModelBuilder; nil for YAML-loaded models (Pass 3 covers YAML).
+        @label_source_loc = attrs[:label_source_loc]
+        @label_plural_source_loc = attrs[:label_plural_source_loc]
+
+        validate!
+      end
+
+      def self.from_hash(hash)
+        new(
+          name: hash["name"],
+          label: hash["label"],
+          label_plural: hash["label_plural"],
+          table_name: hash["table_name"],
+          fields: parse_fields(hash["fields"]),
+          validations: parse_validations(hash["validations"]),
+          associations: parse_associations(hash["associations"], hash["name"]),
+          scopes: (hash["scopes"] || []).map { |s| HashUtils.stringify_deep(s) },
+          events: parse_events(hash["events"]),
+          options: hash["options"] || {},
+          display_templates: parse_display_templates(hash["display_templates"]),
+          virtual_columns: parse_virtual_columns(hash),
+          indexes: parse_indexes(hash["indexes"]),
+          positioning_config: normalize_positioning(hash["positioning"]),
+          data_source_config: hash["data_source"],
+          raw_hash: hash,
+          abstract: hash["abstract"] == true,
+          inherits: hash["inherits"],
+          sti_child: hash[ModelInheritanceResolver::STI_CHILD_KEY] == true,
+          bind_to: hash["bind_to"],
+          bind_to_apply: hash["bind_to_apply"],
+          slug_field: hash["slug_field"],
+          label_source_loc: hash["_label_source_loc"],
+          label_plural_source_loc: hash["_label_plural_source_loc"]
+        )
+      end
+
+      # i18n_check Phase 3a façade — returns `{ "file" => ..., "line" => N }`
+      # for the DSL line that set this attribute, or nil when the model
+      # was loaded from YAML (or the attribute was not set at all).
+      # See `docs/design/i18n_consistency_check.md` §B "Façade method
+      # signatures".
+      def source_location_for(attribute)
+        case attribute
+        when :label        then @label_source_loc
+        when :label_plural then @label_plural_source_loc
+        end
+      end
+
+      # Yields per-field label info for the i18n_check lint walker.
+      # Includes EVERY field — author-set explicit labels and humanize
+      # fallbacks alike. The walker uses the missing-translation check
+      # to decide whether to flag (a humanize-fallback field with no
+      # locale entry is still broken UX in non-default locales).
+      # Source is nil for fields without an explicit DSL `label:`.
+      def each_field
+        return enum_for(:each_field) unless block_given?
+        fields.each do |field|
+          yield(label: field.label, field: field.name, source: field.label_source_loc)
+        end
+      end
+
+      # Returns the names of named scopes declared in the YAML `scopes:`
+      # block as Strings. Scopes are stored as String-keyed Hashes after
+      # `HashUtils.stringify_deep` (see `from_hash`), so the right
+      # accessor is `s["name"]`. Falls back to Symbol key, then to the
+      # entry's `to_s` for legacy bare-symbol forms.
+      def scope_names
+        scopes.map { |s| s.is_a?(Hash) ? (s["name"] || s[:name]).to_s : s.to_s }
+      end
+
+      # Yields per-enum-value labels. The source location is the
+      # enclosing field declaration (`field :status, :enum, values: { … }`),
+      # not the specific value entry — see spec §I "Special case: enum
+      # value labels". Pass 2 (AST) catches the precise value pair.
+      def each_enum_value
+        return enum_for(:each_enum_value) unless block_given?
+        fields.each do |field|
+          next unless field.enum?
+          field.enum_values.each do |entry|
+            next unless entry.is_a?(Hash)
+            value = entry["value"] || entry[:value]
+            next if value.nil?
+            label  = entry["label"] || entry[:label]
+            source = entry["_label_source_loc"] || entry[:_label_source_loc]
+            yield(label: label, field: field.name, value: value, source: source)
+          end
+        end
+      end
+
+      # Returns the singular model label resolved via i18n.
+      def resolved_label
+        I18n.t("lcp_ruby.models.#{name}.one", default: @label)
+      end
+
+      def timestamps?
+        options.fetch("timestamps", true)
+      end
+
+      def label_method
+        options["label_method"] || "to_s"
+      end
+
+      def custom_fields_enabled?
+        options.fetch("custom_fields", false) == true
+      end
+
+      def abstract?
+        @abstract == true
+      end
+
+      def sti_parent?
+        options.fetch("sti", false) == true && !sti_child?
+      end
+
+      def sti_child?
+        @sti_child == true
+      end
+
+      # Returns the STI parent model name, or nil if not an STI child.
+      def sti_parent_name
+        @inherits if sti_child?
+      end
+
+      def virtual?
+        table_name == "_virtual"
+      end
+
+      # Returns true if this model binds to an existing ActiveRecord class in the host app.
+      def bind_to? = bind_to.present?
+
+      # Normalized bind_to class name for display in error / warning / log messages:
+      # strips the leading "::" so output reads "LcpRuby::User" not "::LcpRuby::User".
+      # Returns nil for non-bind_to models.
+      def display_bind_to
+        bind_to&.to_s&.delete_prefix("::")
+      end
+
+      # Required column names for every `lcp_managed: true` belongs_to on
+      # this model. Polymorphic associations contribute both `<name>_id`
+      # and `<name>_type`; non-polymorphic contribute just the FK column.
+      # Used by SchemaManager (which columns to add) and Engine (the
+      # auto_migrate=false escape hatch).
+      # Memoized — ModelDefinition is immutable after initialize, same
+      # invariant `belongs_to_fk_map` already relies on.
+      def managed_fk_columns
+        @managed_fk_columns ||= associations
+          .select { |a| a.belongs_to? && a.lcp_managed? }
+          .flat_map { |a| a.polymorphic ? [ a.foreign_key, "#{a.name}_type" ] : [ a.foreign_key ] }
+      end
+
+      # Returns true if this model is backed by an external data source (REST API, host adapter).
+      def api_model?
+        @data_source_config.is_a?(Hash) && @data_source_config["type"].present?
+      end
+
+      # Returns the data source type as a symbol: :db, :rest_json, or :host.
+      def data_source_type
+        return :db unless api_model?
+
+        case @data_source_config["type"]
+        when "rest_json" then :rest_json
+        when "host" then :host
+        else :db
+        end
+      end
+
+      # Returns supported filter operators for this model's data source.
+      # Falls back to a standard set for DB models.
+      def supported_filter_operators
+        return nil unless api_model?
+
+        @data_source_config["supported_operators"]
+      end
+
+      def soft_delete?
+        boolean_or_hash_option("soft_delete").first
+      end
+
+      def soft_delete_options
+        boolean_or_hash_option("soft_delete").last
+      end
+
+      def soft_delete_column
+        soft_delete_options.fetch("column", "discarded_at")
+      end
+
+      def auditing?
+        boolean_or_hash_option("auditing").first
+      end
+
+      def auditing_options
+        boolean_or_hash_option("auditing").last
+      end
+
+      def userstamps?
+        boolean_or_hash_option("userstamps").first
+      end
+
+      def userstamps_options
+        boolean_or_hash_option("userstamps").last
+      end
+
+      def userstamps_creator_field
+        userstamps_options.fetch("created_by", "created_by_id")
+      end
+
+      def userstamps_updater_field
+        userstamps_options.fetch("updated_by", "updated_by_id")
+      end
+
+      def userstamps_store_name?
+        userstamps_options.fetch("store_name", false) == true
+      end
+
+      def userstamps_creator_association_name
+        userstamps_options.fetch("created_by_association",
+          strip_id_suffix(userstamps_creator_field))
+      end
+
+      def userstamps_updater_association_name
+        userstamps_options.fetch("updated_by_association",
+          strip_id_suffix(userstamps_updater_field))
+      end
+
+      def userstamps_creator_name_field
+        return nil unless userstamps_store_name?
+        userstamps_options.fetch("created_by_name_field",
+          "#{strip_id_suffix(userstamps_creator_field)}_name")
+      end
+
+      def userstamps_updater_name_field
+        return nil unless userstamps_store_name?
+        userstamps_options.fetch("updated_by_name_field",
+          "#{strip_id_suffix(userstamps_updater_field)}_name")
+      end
+
+      def userstamp_column_names
+        return [] unless userstamps?
+
+        cols = [ userstamps_creator_field, userstamps_updater_field ]
+        if userstamps_store_name?
+          cols << userstamps_creator_name_field
+          cols << userstamps_updater_name_field
+        end
+        cols
+      end
+
+      def tree?
+        boolean_or_hash_option("tree").first
+      end
+
+      def tree_options
+        @tree_options ||= boolean_or_hash_option("tree").last
+      end
+
+      def tree_parent_field
+        tree_options.fetch("parent_field", "parent_id")
+      end
+
+      def tree_children_name
+        tree_options.fetch("children_name", "children")
+      end
+
+      def tree_parent_name
+        tree_options.fetch("parent_name", "parent")
+      end
+
+      def tree_dependent
+        tree_options.fetch("dependent", "destroy")
+      end
+
+      def tree_max_depth
+        tree_options.fetch("max_depth", 10)
+      end
+
+      def tree_ordered?
+        tree_options.fetch("ordered", false) == true
+      end
+
+      def tree_position_field
+        tree_options.fetch("position_field", "position")
+      end
+
+      def field(name)
+        fields.find { |f| f.name == name.to_s }
+      end
+
+      # Look up a belongs_to association by name. Returns nil when the name
+      # doesn't match or matches a non-belongs_to (has_many, has_one, polymorphic
+      # through) association.
+      def find_belongs_to(name)
+        assoc = associations.find { |a| a.name == name.to_s }
+        assoc if assoc&.belongs_to?
+      end
+
+      def has_uniqueness_validation?(field_name)
+        name = field_name.to_s
+        f = field(name)
+        (f && f.validations.any? { |v| v.type == "uniqueness" }) ||
+          validations.any? { |v| v.type == "uniqueness" && v.target_field == name }
+      end
+
+      def has_index_for?(field_name)
+        name = field_name.to_s
+        indexes.any? { |idx|
+          cols = Array(idx["columns"] || idx["column"])
+          cols.include?(name)
+        }
+      end
+
+      def parameterized_scopes
+        scopes.select { |s| s["type"] == "parameterized" }
+      end
+
+      def parameterized_scope(name)
+        parameterized_scopes.find { |s| s["name"] == name.to_s }
+      end
+
+      def enum_fields
+        fields.select(&:enum?)
+      end
+
+      # Bind-to applicator features that must run even if not listed in
+      # `bind_to_apply`, because the corresponding YAML-declared virtual fields
+      # are otherwise unreachable at runtime.
+      def bind_to_auto_features
+        features = []
+        features << "enums" if enum_fields.any?(&:virtual?)
+        features << "service_accessors" if fields.any?(&:service_accessor?)
+        # Auto-enable defaults so bind_to models get the same default-on-create
+        # semantics as dynamic LCP models. Without this, fields like
+        # `theme: enum, default: auto, source: json_field` on a bind_to model
+        # never get the after_initialize callback that writes the default into
+        # the underlying store — host.create! leaves the JSON key absent.
+        features << "defaults" if fields.any? { |f| !f.default.nil? }
+        features
+      end
+
+      def display_template(name = "default")
+        display_templates[name.to_s]
+      end
+
+      def virtual_column(name)
+        virtual_columns[name.to_s]
+      end
+
+      def virtual_column_names
+        virtual_columns.keys
+      end
+
+      # Backward compatibility aliases
+      alias_method :aggregate, :virtual_column
+      alias_method :aggregate_names, :virtual_column_names
+
+      def positioned?
+        @positioning_config.present?
+      end
+
+      def positioning_field
+        positioning_config&.fetch("field", "position") || "position"
+      end
+
+      def positioning_scope
+        Array(positioning_config&.fetch("scope", nil)).compact
+      end
+
+      # Predicate paralleling auditing?, tree?, positioned?, soft_delete? — true
+      # when this model declares a workflow (via Workflow::Registry, populated
+      # at engine boot from any of the three sources: YAML/DSL, DB, host adapter).
+      # Requires Workflow::Registry to be `available?` (Setup.apply! has run);
+      # see lib/tasks/lcp_ruby.rake which invokes Setup.apply! before validation.
+      def workflow?
+        !workflow.nil?
+      end
+
+      # Returns the registered workflow object for this model, or nil if no
+      # workflow is declared (or Workflow::Registry isn't available yet).
+      # Memoized. Side-benefit: collapses the duplicated workflow_for_model
+      # memoizers in presenter/action_set.rb and presenter/layout_builder.rb
+      # to a single call site (deferred to follow-up PR).
+      def workflow
+        return @workflow if defined?(@workflow)
+
+        @workflow = if LcpRuby::Workflow::Registry.available?
+          LcpRuby::Workflow::Registry.workflow_for_model(name)
+        end
+      end
+
+      # Returns the macros this model declares, as an array of symbols.
+      # Consumed by Metadata::ReservedNames.reserved_clashes_for_macro to
+      # iterate macro-specific reserved-name lookups, and by future Phase 3
+      # ConfigurationValidator passes that need a single source of truth for
+      # "which macros does this model declare." Memoized.
+      def declared_macros
+        @declared_macros ||= [].tap do |m|
+          m << :auditing if auditing?
+          m << :tree if tree?
+          m << :positioning if positioned?
+          m << :workflow if workflow?
+        end
+      end
+
+      # Neutral primary-key column accessor. Defaults to "id" to match Rails.
+      # Overridden by custom_primary_key.md Tier 2 when/if that spec lands.
+      def primary_key_column
+        "id"
+      end
+
+      # Neutral primary-key type accessor. Defaults to :bigint to match Rails.
+      # Overridden by custom_primary_key.md Tier 1 when/if that spec lands.
+      def primary_key_type
+        :bigint
+      end
+
+      # Returns a Hash mapping FK field name to its belongs_to AssociationDefinition.
+      # e.g. { "company_id" => <AssociationDefinition name="company"> }
+      # Memoized since it's called from multiple places (ColumnSet, DependencyCollector, PermissionEvaluator).
+      # Includes tree-generated parent association when tree? is enabled.
+      def belongs_to_fk_map
+        @belongs_to_fk_map ||= begin
+          map = associations
+            .select { |a| a.type == "belongs_to" && a.foreign_key.present? }
+            .each_with_object({}) { |a, h| h[a.foreign_key] = a }
+
+          # Add tree-generated parent association if not already present
+          if tree? && !map.key?(tree_parent_field)
+            map[tree_parent_field] = AssociationDefinition.new(
+              type: "belongs_to",
+              name: tree_parent_name,
+              target_model: name,
+              foreign_key: tree_parent_field,
+              required: false
+            )
+          end
+
+          map
+        end
+      end
+
+      private
+
+      def strip_id_suffix(field_name)
+        field_name.end_with?("_id") ? field_name.chomp("_id") : field_name
+      end
+
+      def boolean_or_hash_option(key)
+        value = options[key]
+        case value
+        when true then [ true, {} ]
+        when Hash then [ true, value ]
+        else [ false, {} ]
+        end
+      end
+
+      def validate!
+        raise MetadataError, "Model name is required" if @name.blank?
+        validate_field_names_unique!
+        validate_virtual_column_names_unique!
+        validate_slug_field!
+      end
+
+      def validate_field_names_unique!
+        names = fields.map(&:name)
+        duplicates = names.select { |n| names.count(n) > 1 }.uniq
+        if duplicates.any?
+          raise MetadataError, "Duplicate field names in model '#{@name}': #{duplicates.join(', ')}"
+        end
+      end
+
+      def validate_virtual_column_names_unique!
+        field_names = fields.map(&:name)
+        collisions = virtual_column_names & field_names
+        if collisions.any?
+          raise MetadataError, "Model '#{@name}': virtual column names collide with field names: #{collisions.join(', ')}"
+        end
+      end
+
+      def validate_slug_field!
+        return unless @slug_field
+
+        f = field(@slug_field)
+        unless f
+          raise MetadataError, "Model '#{@name}': slug_field '#{@slug_field}' references non-existent field"
+        end
+
+        string_compatible_types = %w[string email url]
+        unless string_compatible_types.include?(f.type)
+          type_def = LcpRuby::Types::Registry.lookup(f.type) if defined?(LcpRuby::Types::Registry)
+          resolved = type_def&.respond_to?(:column_type) ? type_def.column_type.to_s : nil
+          unless resolved == "string"
+            raise MetadataError, "Model '#{@name}': slug_field '#{@slug_field}' must be a string-compatible type, got '#{f.type}'"
+          end
+        end
+
+        if f.virtual?
+          raise MetadataError, "Model '#{@name}': slug_field '#{@slug_field}' must be a DB-backed column (not virtual)"
+        end
+      end
+
+      private_class_method def self.normalize_positioning(raw)
+        case raw
+        when true
+          { "field" => "position" }
+        when Hash
+          result = {}
+          result["field"] = (raw["field"] || "position").to_s
+          result["scope"] = Array(raw["scope"]).map(&:to_s) if raw["scope"]
+          result
+        when nil, false
+          nil
+        end
+      end
+
+      def self.parse_fields(fields_data)
+        return [] unless fields_data.is_a?(Array)
+        fields_data.map { |f| FieldDefinition.from_hash(f) }
+      end
+
+      def self.parse_validations(validations_data)
+        return [] unless validations_data.is_a?(Array)
+        validations_data.map { |v| ValidationDefinition.new(v) }
+      end
+
+      def self.parse_associations(associations_data, owner_name = nil)
+        return [] unless associations_data.is_a?(Array)
+        associations_data.map { |a| AssociationDefinition.from_hash(a, owner_name) }
+      end
+
+      def self.parse_events(events_data)
+        return [] unless events_data.is_a?(Array)
+        events_data.map { |e| EventDefinition.from_hash(e) }
+      end
+
+      # Parse both "aggregates" and "virtual_columns" keys, merge, and error on collision.
+      def self.parse_virtual_columns(hash)
+        agg_data = hash["aggregates"] || {}
+        vc_data = hash["virtual_columns"] || {}
+
+        if agg_data.is_a?(Hash) && vc_data.is_a?(Hash)
+          collisions = agg_data.keys.map(&:to_s) & vc_data.keys.map(&:to_s)
+          if collisions.any?
+            raise MetadataError, "Model '#{hash['name']}': name collision between aggregates and virtual_columns: #{collisions.join(', ')}"
+          end
+        end
+
+        merged = {}
+        parse_vc_hash(agg_data, merged) if agg_data.is_a?(Hash)
+        parse_vc_hash(vc_data, merged) if vc_data.is_a?(Hash)
+        merged
+      end
+
+      def self.parse_vc_hash(data, result)
+        data.each do |name, hash|
+          result[name.to_s] = VirtualColumnDefinition.from_hash(name, hash)
+        end
+      end
+
+      def self.parse_display_templates(data)
+        return {} unless data.is_a?(Hash)
+        data.each_with_object({}) do |(name, hash), result|
+          result[name.to_s] = DisplayTemplateDefinition.from_hash(name, hash)
+        end
+      end
+
+      def self.parse_indexes(data)
+        return [] unless data.is_a?(Array)
+        data.map { |idx| HashUtils.stringify_deep(idx) }
+      end
+    end
+  end
+end

data/lib/lcp_ruby/metadata/model_hash_merger.rb

@@ -0,0 +1,88 @@
+require "set"
+
+module LcpRuby
+  module Metadata
+    # Merges a parent (abstract) model hash into a child model hash.
+    # Operates on raw hashes before ModelDefinition.from_hash is called.
+    module ModelHashMerger
+      # Named-array keys: arrays of hashes where each item has a "name" key.
+      # Child items with the same name override parent items; child-only items are appended.
+      NAMED_ARRAY_KEYS = Set.new(%w[fields associations scopes events]).freeze
+
+      # Hash keys: merged by key, child wins on collision.
+      HASH_KEYS = Set.new(%w[virtual_columns display_templates]).freeze
+
+      # Additive array keys: concatenated, no override by name.
+      ADDITIVE_ARRAY_KEYS = Set.new(%w[validations indexes]).freeze
+
+      # Identity keys: never inherited, always child's own.
+      IDENTITY_KEYS = Set.new(%w[name table_name label label_plural slug_field]).freeze
+
+      # Keys stripped from the merged result.
+      STRIP_KEYS = Set.new(%w[abstract inherits]).freeze
+
+      # All other keys (positioning, data_source, etc.) fall through to the
+      # default branch: child wins if present, otherwise inherited from parent.
+
+      def self.merge(parent_hash, child_hash)
+        result = {}
+
+        # Start with parent as base, skip identity/strip keys
+        parent_hash.each do |key, value|
+          next if IDENTITY_KEYS.include?(key) || STRIP_KEYS.include?(key)
+          result[key] = value.deep_dup
+        end
+
+        # Apply child values
+        child_hash.each do |key, value|
+          next if STRIP_KEYS.include?(key)
+
+          if IDENTITY_KEYS.include?(key)
+            result[key] = value
+          elsif NAMED_ARRAY_KEYS.include?(key)
+            result[key] = merge_named_arrays(result[key], value)
+          elsif HASH_KEYS.include?(key)
+            result[key] = (result[key] || {}).merge(child_hash[key] || {})
+          elsif ADDITIVE_ARRAY_KEYS.include?(key)
+            result[key] = concat_arrays(result[key], value)
+          elsif key == "options"
+            result[key] = (result[key] || {}).deep_merge(value || {})
+          else
+            # Scalar keys and any unknown keys: child wins
+            result[key] = value.deep_dup
+          end
+        end
+
+        # Clean up empty collections
+        result.delete_if { |k, v| (v.is_a?(Array) && v.empty?) || (v.is_a?(Hash) && v.empty?) }
+
+        result
+      end
+
+      def self.merge_named_arrays(parent_items, child_items)
+        parent_items = Array(parent_items)
+        child_items = Array(child_items)
+
+        child_names = child_items.each_with_object({}) { |item, h| h[item["name"]] = item.deep_dup }
+
+        merged = parent_items.map do |parent_item|
+          if child_names.key?(parent_item["name"])
+            child_names.delete(parent_item["name"])
+          else
+            parent_item.deep_dup
+          end
+        end
+
+        # Append remaining child-only items
+        merged.concat(child_names.values)
+        merged
+      end
+      private_class_method :merge_named_arrays
+
+      def self.concat_arrays(parent_array, child_array)
+        Array(parent_array) + Array(child_array)
+      end
+      private_class_method :concat_arrays
+    end
+  end
+end