lcp 0.1.0

data/lib/generators/lcp_ruby/entity_generator.rb

@@ -0,0 +1,1104 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "active_support/core_ext/string"
+require "bigdecimal"
+require "erb"
+require "fileutils"
+require "ostruct" # for generator_macro_options duck-type wrapper
+require_relative "format_support"
+require_relative "../../lcp_ruby/generators/prerequisites"
+require_relative "../../lcp_ruby/generators/entity_menu_writer"
+require_relative "entity/field_descriptor"
+require_relative "entity/field_token_parser"
+require_relative "entity/role_discovery"
+require_relative "entity/color_palette"
+
+module LcpRuby
+  module Generators
+    class EntityGenerator < Rails::Generators::NamedBase
+      include LcpRuby::Generators::Prerequisites
+      include FormatSupport
+
+      source_root File.expand_path("templates/entity", __dir__)
+
+      desc "Generate model + presenter + permissions + view group for a new LCP entity"
+
+      argument :fields, type: :array, default: [],
+        banner: "field:type field:type ..."
+
+      class_option :label_method, type: :string, required: true,
+        desc: "Field used as record label (mandatory; must match a declared field token)"
+      class_option :display_template, type: :string,
+        desc: "Optional display_template string, e.g. \"{number} ({total})\""
+      class_option :searchable_fields, type: :string,
+        desc: "Comma-separated field names enabled in quick search"
+      class_option :validate, type: :boolean, default: false,
+        desc: "Run ConfigurationValidator on the whole config after writing"
+      class_option :auto_add_inverses, type: :boolean, default: false,
+        desc: "Append `has_many` to target DSL model files for each non-polymorphic " \
+              "belongs_to (idempotent; v1 supports DSL targets only — YAML targets " \
+              "and edge cases like multi-target / self-ref / bind_to / STI emit a hint instead)."
+      class_option :soft_delete, type: :boolean, default: false
+      class_option :auditing, type: :boolean, default: false
+      class_option :custom_fields, type: :boolean, default: false
+      class_option :positioning, type: :boolean, default: false
+      class_option :tree, type: :boolean, default: false
+      class_option :index_fields, type: :string,
+        desc: "Comma-separated ordered list of fields for the index section"
+      class_option :form_layout, type: :string, default: "flat",
+        enum: %w[flat tabs]
+      class_option :default_sort, type: :string,
+        desc: "Default sort: 'field' (defaults :desc) or 'field,asc' / 'field,desc'. " \
+              "Field must match a declared field token. When omitted, no default_sort is emitted " \
+              "(runtime falls back to id)."
+      class_option :menu, type: :string,
+        desc: "Menu placement (D7): [<section>:]ROOT|<DropdownLabel>[:bottom|:right]. " \
+              "Writes entry above the matching `# lcp:menu` marker in config/lcp_ruby/menu.yml."
+      class_option :menu_icon, type: :string,
+        desc: "Lucide icon name for the menu entry/dropdown. Requires --menu."
+
+      SYSTEM_FIELDS = %i[id created_at updated_at created_by_id updated_by_id].freeze
+
+      # Feature flags that require a backing column declared in `fields:` for
+      # ConfigurationValidator to accept the configuration. Each entry: [flag, field].
+      # See `inject_synthetic_fields!` for the rationale.
+      SYNTHETIC_FIELDS = [
+        [ :positioning, :position ],
+        [ :tree,        :parent_id ]
+      ].freeze
+
+      def parse_fields
+        @warnings = []
+        # Phase 2 of type-system defaults: the generator now consults the
+        # type registry for null_false_validation, default_index_visible,
+        # renderer, and reserved_clashes. The registry is normally populated
+        # at engine boot (engine.rb:246), but the generator runs from the
+        # `rails generate` command without a full engine boot — so we
+        # register built-ins lazily here. Idempotent (register_all! overwrites
+        # by name).
+        Types::BuiltInTypes.register_all!
+        @descriptors = Entity::FieldTokenParser.parse(fields)
+        inject_synthetic_fields!
+      end
+
+      # Some feature flags require a backing column declared in `fields:` for
+      # ConfigurationValidator to accept the configuration:
+      #   --positioning  →  `position` (acts_as_list expects an explicit field;
+      #                     without it: "positioning field 'position' is not defined").
+      #   --tree         →  `parent_id` (validator
+      #                     `configuration_validator.rb:1228` requires
+      #                     "tree parent_field 'parent_id' must be declared in fields";
+      #                     the showcase Category model declares it for the same reason).
+      # Synthetic descriptors are marked `:hidden` so they do not appear in the
+      # generated index/show/form sections — these are platform-managed columns,
+      # not editable user content. Skipped if the user already declared the field.
+      def inject_synthetic_fields!
+        SYNTHETIC_FIELDS.each do |flag, field_name|
+          next unless options[flag]
+          next if @descriptors.any? { |d| d.name == field_name }
+          # `synthetic: true` marks the descriptor as generator-injected (not
+          # user-declared) so check_reserved_names! skips macro-clash checks
+          # on it — the synthetic positioning :position field IS the macro's
+          # column, not a separate user field that conflicts with it.
+          @descriptors << Entity::FieldDescriptor.new(
+            name: field_name, type: :integer,
+            enum_values: nil, modifiers: { hidden: true, synthetic: true }, options: {}
+          )
+        end
+      end
+
+      def preflight
+        validate_format
+        raise Thor::Error, "At least one field token is required." if @descriptors.empty?
+        check_reserved_names!
+        check_field_types!
+        check_label_method!
+        check_belongs_to_targets!
+        check_polymorphic_conflicts!
+        check_default_values!
+        check_renderer_overrides!
+        validate_searchable_fields!
+        validate_index_fields!
+        validate_display_template!
+        validate_default_sort!
+      end
+
+      # Hook consumed by the `Prerequisites` concern's `check_lcp_prerequisites!`
+      # Thor task. Returns features required by *option-driven* flags
+      # (--auditing → audit_log, --custom-fields → custom_field_definition).
+      # Static prereqs would go via `requires_features` at class level; entity
+      # has none.
+      def lcp_dynamic_required_features
+        out = []
+        out << "auditing"      if options[:auditing]
+        out << "custom_fields" if options[:custom_fields]
+        out
+      end
+
+      # Preflight for --menu. Runs BEFORE any file write so a missing marker /
+      # malformed flag / position-on-dropdown error aborts without leaving
+      # half-generated model/presenter/permissions on disk
+      # (D7 §"Open Question 2: --menu errors in middle of multi-step generation").
+      # Stashes the plan in @menu_write_plan for write_menu_entry to consume.
+      def plan_menu_entry
+        @menu_write_plan = nil
+        return unless options[:menu]
+
+        menu_path = File.join(destination_root, "config/lcp_ruby/menu.yml")
+        unless File.exist?(menu_path)
+          raise Thor::Error,
+            "menu.yml at config/lcp_ruby/menu.yml is missing. " \
+            "Run `rails generate lcp_ruby:install` first or add the file manually."
+        end
+
+        @menu_yml_lines = File.readlines(menu_path)
+        scan_result = LcpRuby::Generators::EntityMenuWriter.scan(@menu_yml_lines)
+
+        if scan_result[:markers].empty?
+          raise Thor::Error,
+            "menu.yml has no `# lcp:menu <section>` insertion markers. " \
+            "Re-run `rails generate lcp_ruby:install` (which seeds markers via " \
+            "--menu-layout=top|sidebar|both) or add a marker manually."
+        end
+
+        flag = LcpRuby::Generators::EntityMenuWriter.parse_flag(
+          options[:menu],
+          available_sections: scan_result[:sections_present]
+        )
+
+        @menu_write_plan = LcpRuby::Generators::EntityMenuWriter.plan_insert(
+          scan_result,
+          section: flag[:section],
+          parent: flag[:parent],
+          view_group: singular_name,
+          icon: options[:menu_icon],
+          position: flag[:position]
+        )
+      end
+
+      # Standalone check: --menu-icon without --menu is an error even when
+      # --menu is not provided (avoids silent no-op).
+      def validate_menu_icon_flag
+        return unless options[:menu_icon] && !options[:menu]
+        raise Thor::Error, "--menu-icon requires --menu; icons are only meaningful with explicit placement."
+      end
+
+      def create_model
+        copy_dsl_or_yaml "model.rb",
+          dsl_target: "config/lcp_ruby/models/#{singular_name}.rb",
+          yaml_target: "config/lcp_ruby/models/#{singular_name}.yml"
+      end
+
+      def create_presenter
+        copy_dsl_or_yaml "presenter.rb",
+          dsl_target: "config/lcp_ruby/presenters/#{plural_name}.rb",
+          yaml_target: "config/lcp_ruby/presenters/#{plural_name}.yml"
+      end
+
+      def create_permissions
+        @roles = Entity::RoleDiscovery.call(destination_root) { |w| @warnings << w }
+        template "permissions.yml", "config/lcp_ruby/permissions/#{singular_name}.yml"
+      end
+
+      def create_view_group
+        copy_dsl_or_yaml "view_group.rb",
+          dsl_target: "config/lcp_ruby/views/#{singular_name}.rb",
+          yaml_target: "config/lcp_ruby/views/#{singular_name}.yml"
+      end
+
+      # Writes the planned `- view_group: <name>` entry into menu.yml. Plan
+      # was computed in plan_menu_entry (preflight); we only need to splice
+      # and re-validate here. Backup is overwriteable single-shot so configurator
+      # can roll back the menu mutation with a single `mv` without rolling back
+      # the other generator outputs (which stay valid independently).
+      def write_menu_entry
+        return if @menu_write_plan.nil?
+
+        if @menu_write_plan[:action] == :skip
+          say_status :skip, @menu_write_plan[:message]
+          return
+        end
+
+        menu_path = File.join(destination_root, "config/lcp_ruby/menu.yml")
+        backup_path = File.join(destination_root, "config/lcp_ruby/.menu.yml.bak")
+        FileUtils.cp(menu_path, backup_path)
+
+        LcpRuby::Generators::EntityMenuWriter.apply!(menu_path, @menu_write_plan,
+          cached_lines: @menu_yml_lines)
+        say_status :update, "config/lcp_ruby/menu.yml"
+
+        validate_menu_post_write!(menu_path, backup_path)
+      end
+
+      # Must run before post_validate so the validator does not see the
+      # "no corresponding has_many" warnings that auto-add just resolved.
+      def auto_add_reverse_associations
+        @inverse_suggestions = compute_inverse_suggestions
+        return if @inverse_suggestions.empty?
+        return unless options[:auto_add_inverses]
+        process_inverse_suggestions!
+      end
+
+      def post_validate
+        return unless options[:validate]
+        run_configuration_validator!
+      end
+
+      def show_post_install_message
+        say ""
+        say "LCP entity '#{singular_name}' generated.", :green
+        say ""
+        say "Generated files:"
+        say "  - config/lcp_ruby/models/#{singular_name}.#{format_extension}"
+        say "  - config/lcp_ruby/presenters/#{plural_name}.#{format_extension}"
+        say "  - config/lcp_ruby/permissions/#{singular_name}.yml"
+        say "  - config/lcp_ruby/views/#{singular_name}.#{format_extension}"
+        if @warnings.any?
+          say ""
+          @warnings.each { |w| say_status :warn, w, :yellow }
+        end
+        say ""
+        show_reverse_association_hints
+        show_polymorphic_hint
+        say "Next steps:"
+        next_steps.each_with_index do |step, i|
+          say "  #{i + 1}. #{step}"
+        end
+        say ""
+        say "Tip: in bash, single-quote any field token whose braces contain a comma " \
+            "(e.g. `'customer:belongs_to{required,link}'`) — bash brace-expands `{a,b}` patterns."
+        say ""
+      end
+
+      private
+
+      def show_reverse_association_hints
+        return if @inverse_suggestions.empty?
+
+        if options[:auto_add_inverses]
+          show_auto_add_summary
+        else
+          show_manual_reverse_hints
+        end
+      end
+
+      def show_manual_reverse_hints
+        say "Reverse associations:"
+        @inverse_suggestions.each do |s|
+          say "  - On model :#{s[:target_model]}, add: #{s[:line].lstrip}"
+        end
+        say_skip_inverse_check_note
+        say ""
+      end
+
+      def show_auto_add_summary
+        added   = @inverse_suggestions.select { |s| s[:status] == :auto_added }
+        skipped = @inverse_suggestions.reject { |s| %i[auto_added already_present].include?(s[:status]) }
+
+        if added.any?
+          say "Auto-added reverse associations:"
+          added.each do |s|
+            say "  - #{s[:target_path_relative]}: #{s[:line].lstrip}"
+          end
+          say ""
+        end
+
+        if skipped.any?
+          say "Skipped reverse associations (manual edit needed):"
+          skipped.each do |s|
+            say "  - On model :#{s[:target_model]} — #{skip_reason_phrase(s[:status])}"
+            say "      Suggested: #{s[:line].lstrip}"
+          end
+          say_skip_inverse_check_note
+          say ""
+        end
+      end
+
+      def say_skip_inverse_check_note
+        say "  (For one-directional belongs_to where reverse traversal is intentional, " \
+            "add `skip_inverse_check: true` to silence the validator's reciprocity warning.)"
+      end
+
+      def skip_reason_phrase(status)
+        case status
+        when :skipped_missing       then "target model file not found"
+        when :skipped_yaml          then "target is YAML (auto-add supports DSL targets only in v1)"
+        when :skipped_bind_to       then "target uses `bind_to:` — host AR class owns its associations"
+        when :skipped_sti_child     then "target is an STI child (`inherits:`) — add has_many on the parent"
+        when :skipped_self_ref      then "self-referential belongs_to — add the inverse manually"
+        when :skipped_multi_target  then "multiple belongs_to point at this target — distinct has_many names + foreign_key required"
+        else status.to_s
+        end
+      end
+
+      # FK formula matches `validate_association_reciprocity`:
+      # `conventional_fk = "#{target_model}_id"` because the has_many's
+      # owner *is* the target model, and Rails infers FK from the owner class.
+      def compute_inverse_suggestions
+        descriptors = @descriptors.select { |d| d.belongs_to? && !d.polymorphic? }
+        targets_count = descriptors.group_by(&:target_model).transform_values(&:size)
+
+        descriptors.map do |d|
+          target = d.target_model.to_s
+          actual_fk = "#{d.name}_id"
+          conventional_fk = "#{target}_id"
+          fk_kwarg = actual_fk == conventional_fk ? "" : ", foreign_key: :#{actual_fk}"
+          line = "  has_many :#{plural_name}, model: :#{singular_name}#{fk_kwarg}, dependent: :restrict_with_error"
+
+          status =
+            if d.target_model.to_s == singular_name
+              :skipped_self_ref
+            elsif targets_count[d.target_model] > 1
+              :skipped_multi_target
+            else
+              :manual
+            end
+
+          {
+            target_model: target,
+            target_path: File.join(models_dir, "#{target}.rb"),
+            target_path_relative: "config/lcp_ruby/models/#{target}.rb",
+            line: line,
+            status: status
+          }
+        end
+      end
+
+      # Pre-set statuses (skipped_self_ref, skipped_multi_target from
+      # compute_inverse_suggestions) survive the `next if … != :manual` guard.
+      BIND_TO_RE       = /^\s*bind_to\s/
+      # Matches DSL `inherits :parent` (STI). Trailing \s deliberately
+      # excludes `inherits_from:` (permission/scope inheritance — a
+      # different concept) because `_` is not whitespace. Loosening to
+      # `\binherits` would silently start skipping permission-inherited
+      # models too.
+      STI_INHERITS_RE  = /^\s*inherits\s/
+      private_constant :BIND_TO_RE, :STI_INHERITS_RE
+
+      def process_inverse_suggestions!
+        has_many_re = /^\s*has_many\s+:#{Regexp.escape(plural_name)}\b/
+
+        @inverse_suggestions.each do |s|
+          next if s[:status] != :manual
+
+          target_path_dsl = s[:target_path]
+          target_path_yml = target_path_dsl.sub(/\.rb\z/, ".yml")
+
+          unless File.exist?(target_path_dsl)
+            s[:status] = File.exist?(target_path_yml) ? :skipped_yaml : :skipped_missing
+            next
+          end
+
+          contents = File.read(target_path_dsl)
+          if    contents =~ BIND_TO_RE       then s[:status] = :skipped_bind_to;   next
+          elsif contents =~ STI_INHERITS_RE  then s[:status] = :skipped_sti_child; next
+          elsif contents =~ has_many_re      then s[:status] = :already_present;   next
+          end
+
+          inject_into_file target_path_dsl, before: /\nend\s*\z/ do
+            "\n#{s[:line]}\n"
+          end
+          s[:status] = :auto_added
+        end
+      end
+
+      # Polymorphic associations are intentionally omitted from the generated
+      # index and show sections (validator rejects auto-detection — see
+      # configuration_validator.rb:2980-2983). Tell the configurator so they
+      # know to add custom rendering by hand.
+      def show_polymorphic_hint
+        polymorphic = @descriptors.select(&:polymorphic?)
+        return if polymorphic.empty?
+        say "Polymorphic associations (skipped from default index/show):"
+        polymorphic.each do |d|
+          say "  - :#{d.name} — add a custom renderer or `link_through:` in " \
+              "config/lcp_ruby/presenters/#{plural_name}.#{format_extension}"
+        end
+        say "  Form input still uses :association_select but does not yet " \
+            "support polymorphic targets at runtime — replace by hand."
+        say ""
+      end
+
+      def singular_name = name.underscore.singularize
+      def plural_name   = name.underscore.pluralize
+      def dynamic_class_name = singular_name.camelize
+
+      def next_steps
+        steps = []
+        if @label_method_needs_stub
+          label = @label_method_needs_stub
+          steps << <<~STEP.chomp
+            Define `def #{label}` on the dynamic model. Add to config/initializers/lcp_ruby_extensions.rb:
+                 LcpRuby.on_models_loaded do
+                   LcpRuby::Dynamic::#{dynamic_class_name}.class_eval do
+                     def #{label}
+                       # TODO: implement (e.g. "\#{first_name} \#{last_name}".strip.presence || "(unnamed)")
+                     end
+                   end
+                 end
+               See docs/guides/extensibility.md (Model Extensions).
+          STEP
+        end
+        steps << menu_step
+        steps << "Add translations under config/locales/lcp_ruby/<name>.<locale>.yml for: " \
+                 "lcp_ruby.models.#{singular_name}.{label,label_plural,fields.*}, " \
+                 "lcp_ruby.presenters.#{plural_name}.label"
+        steps << "Run: rails s   (table is created automatically at boot via SchemaManager)"
+        steps << "Run: bundle exec rake lcp_ruby:validate   (cross-checks config)"
+        steps
+      end
+
+      # D7 §"What happens to existing next_steps menu hint" — mode-branched
+      # wording. Step #1 reflects what actually happened (or didn't) with
+      # menu.yml during this generator invocation:
+      #   --menu used + insert/create_dropdown → success summary
+      #   --menu used + idempotent skip → skip notice
+      #   --menu omitted + menu_mode=:auto   → recommend --menu, note auto-append
+      #   --menu omitted + menu_mode=:strict → recommend --menu, warn invisible
+      def menu_step
+        if @menu_write_plan && %i[insert create_dropdown].include?(@menu_write_plan[:action])
+          parent = @menu_write_plan[:parent]
+          section = @menu_write_plan[:section]
+          if @menu_write_plan[:action] == :create_dropdown
+            "Menu dropdown '#{parent}' auto-created in section '#{section}' of " \
+              "config/lcp_ruby/menu.yml with view_group: #{singular_name}."
+          else
+            "Menu entry added to config/lcp_ruby/menu.yml (section '#{section}', parent '#{parent}')."
+          end
+        elsif @menu_write_plan && @menu_write_plan[:action] == :skip
+          "menu.yml already references view_group: #{singular_name} (skipped)."
+        else
+          menu_step_recommendation
+        end
+      end
+
+      def menu_step_recommendation
+        mode = current_menu_mode
+        line1 = "Recommended: re-run with `--menu=[<section>:]ROOT|<DropdownLabel>[:bottom|:right]` " \
+                "for explicit menu placement (`--menu-icon=<lucide-name>` adds an icon)."
+        line2 = if mode == :strict
+                  "Skipped — in :strict mode the entity is NOT in the menu; add it manually or re-run with --menu."
+        else
+                  "Skipped — entity will be auto-appended to top_menu alphabetically."
+        end
+        "#{line1}\n     #{line2}"
+      end
+
+      def current_menu_mode
+        return :auto unless defined?(LcpRuby) && LcpRuby.respond_to?(:configuration)
+        LcpRuby.configuration.menu_mode || :auto
+      rescue StandardError
+        :auto
+      end
+
+      # In-process re-validation after splicing into menu.yml. Failure leaves
+      # menu.yml on disk (configurator inspects what was written) and points
+      # at .menu.yml.bak as the rollback target. Model/presenter/permissions
+      # already exist by now — they're independent of menu correctness, so
+      # rolling them back on a menu-validation issue would be over-broad
+      # (D7 §"On validation failure" rationale).
+      def validate_menu_post_write!(menu_path, backup_path)
+        begin
+          require "lcp_ruby/metadata/loader"
+        rescue LoadError
+          # Loader not available in this context (e.g. dev/test outside Rails) —
+          # skip validation rather than blow up the generator. The boot-time
+          # loader will catch a malformed menu.yml when the host app actually
+          # starts. Narrower than rescuing constant-resolution errors so a typo
+          # *inside* Loader bubbles up loudly.
+          return
+        end
+
+        config_dir = File.dirname(menu_path)
+        loader = LcpRuby::Metadata::Loader.new(config_dir)
+        loader.load_all
+      rescue LcpRuby::MetadataError => e
+        backup_rel = relative_to_original_destination_root(backup_path)
+        menu_rel = relative_to_original_destination_root(menu_path)
+        raise Thor::Error,
+          "menu.yml was modified but now fails validation: #{e.message}\n" \
+          "Original saved to #{backup_rel} — restore manually if needed:\n" \
+          "  mv #{backup_rel} #{menu_rel}"
+      end
+
+      def models_dir
+        File.join(destination_root, "config/lcp_ruby/models")
+      end
+
+      def model_file_exists?(model_name)
+        Dir.glob(File.join(models_dir, "#{model_name}.{rb,yml}")).any?
+      end
+
+      def system_field_descriptors
+        SYSTEM_FIELDS.map do |sym|
+          opts = { system: true }
+          opts[:renderer] = "datetime" if sym == :created_at || sym == :updated_at
+          # Suppresses `sortable: true` in column_options_inline for FK userstamps
+          # (sorting users by their numeric id is not a useful UX). The runtime
+          # treats a missing `sortable:` kwarg as "not sortable" (truthy check at
+          # app/views/lcp_ruby/resources/_table_index.html.erb:65), so emitting no
+          # kwarg matches the spec example output exactly.
+          opts[:sortable] = false      if sym == :created_by_id || sym == :updated_by_id
+          Entity::FieldDescriptor.new(name: sym, type: :system, enum_values: nil, modifiers: {}, options: opts)
+        end
+      end
+
+      # ---------------- pre-flight ----------------
+
+      def check_reserved_names!
+        # Three sources of reserved-name clashes:
+        # 1. AR universals (RESERVED_ATTRIBUTE_NAMES) — clash for every field
+        # 2. Type-driven clashes — e.g. `:enum` field named `value` clashes
+        #    with ActiveRecord::Relation#values via AR's enum macro (C9).
+        #    Walks the base_type chain so custom enum-derived types inherit
+        #    enum's clash list (Decision 11).
+        # 3. Macro-generated method names — :tree, :positioning, :workflow
+        #    each generate methods on the AR class. The list is derived from
+        #    the model's actual macro options (Decision 13) — for the
+        #    generator we wrap CLI flags in an OpenStruct duck-type that
+        #    supplies the same accessors a real ModelDefinition would.
+        ar_universals = LcpRuby::Metadata::ReservedNames::RESERVED_ATTRIBUTE_NAMES
+
+        @descriptors.each do |d|
+          name = d.name.to_s
+          if ar_universals.include?(name)
+            raise Thor::Error,
+              "Field '#{d.name}' is a reserved attribute name (clashes with " \
+              "ActiveRecord). Choose a different name."
+          end
+
+          type_clashes = Types::TypeRegistry.reserved_clashes_for(d.type)
+          next unless type_clashes.include?(name)
+
+          raise Thor::Error,
+            "Field '#{d.name}' (type :#{d.type}) clashes with a method generated " \
+            "by the #{d.type} macro (one of: #{type_clashes.first(8).join(', ')}…). " \
+            "Choose a different name."
+        end
+
+        # Macro-generated clashes — fire only for declared macros (skips when
+        # the corresponding CLI flag is off). Skips synthetic descriptors
+        # (generator-injected platform columns like positioning's :position) —
+        # those ARE the macro's column, not a user-declared conflict.
+        macro_options = generator_macro_options
+        declared_macros.each do |macro|
+          clashes = LcpRuby::Metadata::ReservedNames.reserved_clashes_for_macro(macro, macro_options)
+          @descriptors.each do |d|
+            next if d.modifiers[:synthetic]
+            next unless clashes.include?(d.name.to_s)
+
+            raise Thor::Error,
+              "Field '#{d.name}' clashes with a method/column generated by the " \
+              ":#{macro} macro (one of: #{clashes.join(', ')}). Choose a different name."
+          end
+        end
+      end
+
+      # Macro flags declared via CLI (--tree, --positioning, --auditing). The
+      # generator does not yet expose --workflow as a CLI flag, so :workflow
+      # is never in this list during generator preflight. (Hand-written
+      # workflow models still get C9-for-workflow coverage via
+      # ConfigurationValidator in Phase 3.)
+      def declared_macros
+        macros = []
+        macros << :tree if options[:tree]
+        macros << :positioning if options[:positioning]
+        macros << :auditing if options[:auditing]
+        macros
+      end
+
+      # OpenStruct duck-type wrapping CLI flags — mirrors the accessors that
+      # `ReservedNames.reserved_clashes_for_macro` consumes from a real
+      # `ModelDefinition` (per Decision 13). The generator currently uses
+      # default tree/positioning option values (no `--tree-parent-name=X`
+      # CLI flag exists), so the OpenStruct supplies those defaults.
+      def generator_macro_options
+        OpenStruct.new(
+          tree_parent_name: "parent",
+          tree_children_name: "children",
+          tree_position_field: "position",
+          tree_ordered?: false,
+          positioned?: options[:positioning],
+          positioning_field: "position",
+          workflow: nil
+        )
+      end
+
+      def check_field_types!
+        base = LcpRuby::Metadata::FieldDefinition::BASE_TYPES.map(&:to_sym)
+        business = LcpRuby::Types::BuiltInTypes::DEFINITIONS.keys.map(&:to_sym)
+        associations = %i[belongs_to has_many]
+        known = base + business + associations
+        @descriptors.each do |d|
+          next if known.include?(d.type)
+          @warnings << "Unknown field type '#{d.type}' on field '#{d.name}'. " \
+                       "Skipping built-in type validation — assumed to be a custom type " \
+                       "defined in config/lcp_ruby/types/. Run `bundle exec rake lcp_ruby:validate` " \
+                       "after generation to confirm."
+        end
+      end
+
+      def check_label_method!
+        label = options[:label_method].to_sym
+        declared = @descriptors.map(&:name)
+        unless declared.include?(label)
+          @label_method_needs_stub = label
+          @warnings << "--label-method=#{label} is not a declared field. The generator will " \
+                       "emit `label_method :#{label}` and you must define `def #{label}` on the " \
+                       "dynamic model before booting (see Next steps)."
+          return
+        end
+        matching = @descriptors.find { |d| d.name == label }
+        return unless matching&.belongs_to?
+        @warnings << "--label-method=#{label} points to a belongs_to association. " \
+                     "The runtime will call `to_s` on the associated record, which is rarely the " \
+                     "intended display label. Consider setting label_method on the target model " \
+                     "(`#{matching.target_model}`) instead, or pick a scalar field on this model."
+      end
+
+      def check_belongs_to_targets!
+        @descriptors.select(&:belongs_to?).each do |d|
+          # Polymorphic associations have no compile-time target — the target type
+          # is decided per row at runtime (`<name>_type`). The "target model file
+          # not found" warning is meaningless here.
+          next if d.modifiers[:polymorphic]
+          target = d.target_model
+          next if model_file_exists?(target)
+          @warnings << "belongs_to target '#{target}' not found in #{models_dir} — proceeding anyway. " \
+                       "If the target model has a different name, pass " \
+                       "'#{d.name}:belongs_to{model:NAME}' (and add ',required' if needed)."
+        end
+      end
+
+      def check_polymorphic_conflicts!
+        @descriptors.select(&:belongs_to?).each do |d|
+          next unless d.modifiers[:polymorphic] && d.options[:model]
+          raise Thor::Error,
+            "belongs_to '#{d.name}' cannot specify both {polymorphic} and {model:#{d.options[:model]}}. " \
+            "Polymorphic associations have no compile-time target."
+        end
+      end
+
+      # Validate {default:X} values against the field type before any file
+      # is written. Boolean uses a strict whitelist; numeric types delegate
+      # to Kernel#Integer / Kernel#Float / BigDecimal which raise ArgumentError
+      # on garbage. Without this check, garbage like {default:abc} on integer
+      # silently coerces to 0, and decimal raises mid-template-render leaving
+      # the model file half-written.
+      def check_default_values!
+        @descriptors.each do |d|
+          next unless d.options.key?(:default)
+          validate_default_value!(d)
+        end
+      end
+
+      def validate_default_value!(d)
+        raw = d.options[:default]
+        case d.type
+        when :boolean
+          unless %w[true false].include?(raw)
+            raise Thor::Error,
+              "Invalid {default:#{raw}} for :boolean field '#{d.name}'. Must be 'true' or 'false'."
+          end
+        when :integer
+          Integer(raw)
+        when :float
+          Float(raw)
+        when :decimal
+          BigDecimal(raw)
+        end
+      rescue ArgumentError, TypeError => e
+        raise Thor::Error,
+          "Invalid {default:#{d.options[:default]}} for :#{d.type} field '#{d.name}': #{e.message}"
+      end
+
+      # Emit the {color_map} + {renderer:NAME} override warning once per
+      # descriptor, in pre-flight. `renderer_for` is a pure helper called
+      # repeatedly during template rendering; embedding the warning there
+      # produced 4 duplicate lines per offending descriptor (B1).
+      def check_renderer_overrides!
+        @descriptors.each do |d|
+          next unless d.modifiers[:color_map] && d.options[:renderer]
+          @warnings << "explicit {renderer:#{d.options[:renderer]}} on '#{d.name}' " \
+                       "overrides {color_map}; the color rotation will not be emitted."
+        end
+      end
+
+      def validate_searchable_fields!
+        return if options[:searchable_fields].blank?
+        declared = @descriptors.map { |d| d.name.to_s }
+        requested = options[:searchable_fields].split(",").map(&:strip)
+        unknown = requested - declared
+        unless unknown.empty?
+          raise Thor::Error,
+            "--searchable-fields contains unknown fields: #{unknown.join(', ')}. " \
+            "Each must match a declared field token."
+        end
+        requested.each do |fname|
+          descriptor = @descriptors.find { |d| d.name.to_s == fname }
+          if descriptor&.hidden?
+            raise Thor::Error,
+              "Field '#{fname}' is :hidden and cannot be in --searchable-fields."
+          end
+          next unless descriptor&.belongs_to?
+          @warnings << "searchable_field '#{fname}' is a belongs_to association; " \
+                       "quick-search behavior is undefined for associations and may not work as expected."
+        end
+      end
+
+      def validate_index_fields!
+        return if options[:index_fields].blank?
+        declared = @descriptors.map { |d| d.name.to_s } + SYSTEM_FIELDS.map(&:to_s)
+        unknown = options[:index_fields].split(",").map(&:strip) - declared
+        return if unknown.empty?
+        raise Thor::Error, "--index-fields contains unknown fields: #{unknown.join(', ')}."
+      end
+
+      # Single source of truth for `--default-sort` parsing — consumed by both
+      # `validate_default_sort!` (pre-flight) and `default_sort_pair` (template
+      # render). Returns `[field_str, direction_str_or_nil]`. `direction_str`
+      # may be nil (when no comma) or "" (when trailing comma); the validator
+      # accepts both as "default direction".
+      def parse_default_sort_option
+        return nil if options[:default_sort].blank?
+        field, direction = options[:default_sort].split(",", 2).map { |s| s.to_s.strip }
+        [ field, direction ]
+      end
+
+      def validate_default_sort!
+        parsed = parse_default_sort_option
+        return unless parsed
+        field, direction = parsed
+        if field.empty?
+          raise Thor::Error,
+            "--default-sort='#{options[:default_sort]}' is empty. " \
+            "Use 'field' or 'field,asc'/'field,desc'."
+        end
+        declared = @descriptors.map { |d| d.name.to_s }
+        unless declared.include?(field)
+          raise Thor::Error,
+            "--default-sort references unknown field '#{field}'. Declared: #{declared.join(', ')}."
+        end
+        return if direction.nil? || direction.empty? || %w[asc desc].include?(direction)
+        raise Thor::Error,
+          "--default-sort direction '#{direction}' is invalid. Must be 'asc' or 'desc'."
+      end
+
+      def validate_display_template!
+        return if options[:display_template].blank?
+        declared = @descriptors.map(&:name)
+        options[:display_template].scan(/\{([a-z_][a-z0-9_]*)\}/).flatten.each do |placeholder|
+          next if declared.include?(placeholder.to_sym)
+          @warnings << "--display-template references unknown field '{#{placeholder}}'. " \
+                       "Declared fields: #{declared.join(', ')}."
+        end
+      end
+
+      # ---------------- helpers used by templates ----------------
+
+      def feature_flag_lines
+        lines = []
+        lines << "soft_delete"        if options[:soft_delete]
+        lines << "auditing true"      if options[:auditing]
+        lines << "custom_fields true" if options[:custom_fields]
+        lines << "positioning"        if options[:positioning]
+        lines << "tree true"          if options[:tree]
+        lines
+      end
+
+      def field_options_inline(d)
+        parts = []
+        parts << "values: %w[#{d.enum_values.join(' ')}]" if d.type == :enum && d.enum_values
+        parts << "default: #{coerced_default(d).inspect}" if d.options.key?(:default)
+        parts << "null: false"                            if d.required?
+        parts << "limit: #{d.options[:limit]}"            if d.options[:limit] && d.type == :string
+        format_kwargs(parts)
+      end
+
+      def belongs_to_inline(d)
+        # Always emit `required:` explicitly. Without an explicit kwarg, AR
+        # Rails 5+ defaults `belongs_to` to `required: true`, which silently
+        # rejects nullable parents — a footgun discovered in school audit
+        # (school-improve-tasks-details-aggregated.md C1). Polymorphic and
+        # named-target branches treat this symmetrically; the validator mirrors
+        # the rule for both via `validate_belongs_to_explicit_required`.
+        parts = []
+        if d.modifiers[:polymorphic]
+          parts << "polymorphic: true"
+        else
+          parts << "model: :#{d.target_model}"
+        end
+        parts << "required: #{d.required? ? 'true' : 'false'}"
+        ", " + parts.join(", ")
+      end
+
+      def column_options_inline(d)
+        parts = []
+        # `d.options[:sortable] == false` is the opt-out marker set by
+        # system_field_descriptors for userstamp FK columns — see comment there.
+        parts << "sortable: true"            unless d.association? || d.options[:sortable] == false
+        if (renderer = renderer_for(d))
+          parts << "renderer: :#{renderer}"
+        end
+        # `link: true` is the default for non-polymorphic belongs_to in both
+        # index and show. Without it, ConfigurationValidator rejects the bare
+        # association name (e.g. `column :customer`) as an unknown field
+        # (`configuration_validator.rb:2500-2503` — bare belongs_to names are
+        # accepted only when the entry has `link:` or `link_through:`). The
+        # `{link}` CLI modifier remains parseable but is now a no-op.
+        # Polymorphic associations are excluded from index/show entirely
+        # (`visible_in_presenter_columns`), so they never reach this branch.
+        parts << "link: true"                if d.belongs_to?
+        if (badge = badge_options_kwarg(d))
+          parts << badge
+        end
+        format_kwargs(parts)
+      end
+
+      def field_options_inline_show(d)
+        parts = []
+        if (renderer = renderer_for(d))
+          parts << "renderer: :#{renderer}"
+        end
+        parts << "link: true" if d.belongs_to?
+        if (badge = badge_options_kwarg(d))
+          parts << badge
+        end
+        format_kwargs(parts)
+      end
+
+      # Trailing comma-prefixed kwarg string, or empty when nothing to emit.
+      # Shared by index, show, and form-field inline option builders.
+      def format_kwargs(parts)
+        parts.empty? ? "" : ", " + parts.join(", ")
+      end
+
+      # The `options: { color_map: {...} }` kwarg for an enum descriptor with
+      # `{color_map}` when the resolved renderer is `:badge`. Returns nil
+      # otherwise. Centralised so index and show emit identical output.
+      def badge_options_kwarg(d)
+        return nil unless d.type == :enum && d.modifiers[:color_map] && renderer_for(d) == :badge
+        "options: { color_map: #{Entity::ColorPalette.assign(d.enum_values).inspect} }"
+      end
+
+      def form_field_name(d)
+        d.belongs_to? ? :"#{d.name}_id" : d.name
+      end
+
+      def form_field_options_inline(d)
+        return ", input_type: :association_select" if d.belongs_to?
+        ""
+      end
+
+      # Pure: no side effects. The override warning is emitted once per descriptor
+      # in pre-flight (`check_renderer_overrides!`); this helper only resolves
+      # which renderer symbol applies, and is called repeatedly during template
+      # rendering.
+      def renderer_for(d)
+        if d.options[:system] && (d.name == :created_at || d.name == :updated_at)
+          return :datetime
+        end
+        return d.options[:renderer].to_sym if d.options[:renderer]
+        return :badge if d.modifiers[:color_map]
+        # Phase 2 of type-system defaults: fall through to the type registry's
+        # default renderer when nothing more specific applies. Picks up
+        # `boolean → :boolean_icon`, `enum → :badge`, `text → :truncate`,
+        # `email → :email_link`, etc. without the configurator having to
+        # write `renderer:` explicitly. Returns nil when the type has no
+        # registered default — preserves today's "no renderer = raw value"
+        # behavior for `:string`, `:integer`, `:date`, etc.
+        type_renderer = Types::TypeRegistry.renderer_for(d.type)
+        return type_renderer.to_sym if type_renderer
+
+        nil
+      end
+
+      def coerced_default(d)
+        raw = d.options[:default]
+        return nil if raw.nil?
+        case d.type
+        when :boolean then raw == "true"
+        when :integer then raw.to_i
+        when :float   then raw.to_f
+        when :decimal then BigDecimal(raw)
+        else raw
+        end
+      end
+
+      def validation_lines
+        lines = []
+        @descriptors.each do |d|
+          if d.required? && !d.belongs_to?
+            # Phase 2 of type-system defaults: instead of hardcoding `:presence`,
+            # consult the type registry. For `:boolean` this emits the
+            # canonical `inclusion: { in: [true, false] }` rather than
+            # `:presence` (which would reject `false` because
+            # `false.present? == false` — the C4 footgun). For everything else
+            # the registry returns `[{type: presence}]` by default, so existing
+            # output is preserved.
+            Types::TypeRegistry.null_false_validation_for(d.type).each do |entry|
+              lines << validates_line_for(d.name, entry)
+            end
+          end
+          lines << "validates :#{d.name}, :uniqueness" if d.modifiers[:uniq]
+        end
+        lines
+      end
+
+      # Maps a null_false_validation entry hash to a single `validates` line.
+      # Examples:
+      #   {"type"=>"presence"} → "validates :name, :presence"
+      #   {"type"=>"inclusion","options"=>{"in"=>[true,false]}}
+      #     → "validates :name, :inclusion, in: [true, false]"
+      #   {"type"=>"numericality","options"=>{"greater_than_or_equal_to"=>1}}
+      #     → "validates :name, :numericality, greater_than_or_equal_to: 1"
+      # The DSL accepts `validates(field_name, type, **options)` (model_builder
+      # accepts variadic kwargs), so the rendered line maps directly.
+      def validates_line_for(field_name, entry)
+        type = entry["type"] || entry[:type]
+        options = entry["options"] || entry[:options] || {}
+
+        if options.empty?
+          "validates :#{field_name}, :#{type}"
+        else
+          opts_str = options.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+          "validates :#{field_name}, :#{type}, #{opts_str}"
+        end
+      end
+
+      def index_lines
+        lines = []
+        @descriptors.each do |d|
+          if d.modifiers[:uniq]
+            lines << "index %i[#{d.name}], unique: true"
+          elsif d.modifiers[:index]
+            lines << "index %i[#{d.name}]"
+          end
+        end
+        lines
+      end
+
+      # Index/show: exclude polymorphic associations. The validator rejects them
+      # (configuration_validator.rb:2980-2983) because polymorphic auto-detection
+      # cannot resolve a presenter at boot — the target type is per-row. The
+      # configurator must add custom rendering manually (e.g. via link_through:
+      # to a non-polymorphic association, or a custom renderer). Form keeps
+      # polymorphic so the configurator sees the field placeholder and can
+      # replace `:association_select` with a polymorphic-aware input.
+      def index_columns
+        if options[:index_fields] && !options[:index_fields].empty?
+          # Explicit override — bypass type-driven default_index_visible?
+          # filtering (the configurator asked for these specific fields).
+          # System fields stay queryable so `--index-fields=created_at,...`
+          # still works.
+          requested = options[:index_fields].split(",").map(&:strip)
+          all = (visible_in_presenter_columns + system_field_descriptors)
+          requested.map do |fname|
+            all.find { |d| d.name.to_s == fname }
+          end.compact
+        else
+          visible_in_index_columns + system_field_descriptors
+        end
+      end
+
+      def show_sections
+        buckets = {}
+        visible_in_presenter_columns.each do |d|
+          section = (d.options[:section] || :general).to_sym
+          (buckets[section] ||= []) << d
+        end
+        buckets[:general] ||= []
+        buckets[:general] += system_field_descriptors
+        buckets
+      end
+
+      def form_sections
+        buckets = {}
+        @descriptors.reject(&:hidden?).reject(&:has_many?).each do |d|
+          section = (d.options[:section] || :general).to_sym
+          (buckets[section] ||= []) << d
+        end
+        buckets
+      end
+
+      def visible_in_presenter_columns
+        @descriptors.reject(&:hidden?).reject(&:has_many?).reject(&:polymorphic?)
+      end
+
+      # Phase 2 of type-system defaults: index-specific subset that ADDS
+      # `default_index_visible?(d.type)` on top of the three pre-existing
+      # filters (does NOT replace them). For `:text`, `:rich_text`,
+      # `:attachment`, `:json`, `:array`, `:file` the registry returns false
+      # → those types are dropped from the generated index by default,
+      # fixing C6. Show / form sections continue to use
+      # `visible_in_presenter_columns` so a `:text` body field stays visible
+      # on show pages and editable in forms — only the row-unfriendly INDEX
+      # column drops out. The configurator can override per-presenter with
+      # `display_in_index: true` (Phase 3 validator silences the
+      # row-unfriendly warning when this kwarg is present).
+      def visible_in_index_columns
+        visible_in_presenter_columns.select do |d|
+          Types::TypeRegistry.default_index_visible?(d.type)
+        end
+      end
+
+      def searchable_fields
+        from_flag = (options[:searchable_fields] || "").split(",").map(&:strip).reject(&:empty?).map(&:to_sym)
+        from_modifier = @descriptors.select { |d| d.modifiers[:search] }.map(&:name)
+        (from_flag + from_modifier).uniq
+      end
+
+      # Returns [field_sym, direction_sym] when --default-sort is given,
+      # nil otherwise. The presenter template emits `default_sort` only
+      # when this returns non-nil (school audit C10: no implicit default).
+      # Direction defaults to :desc when omitted; pre-flight rejects
+      # unknown fields and unknown directions, so a defensive whitelist
+      # check here just guards against bypassed-preflight callers.
+      def default_sort_pair
+        parsed = parse_default_sort_option
+        return nil unless parsed
+        field, direction = parsed
+        direction_sym = %w[asc desc].include?(direction) ? direction.to_sym : :desc
+        [ field.to_sym, direction_sym ]
+      end
+
+      # ---------------- --validate ----------------
+
+      def run_configuration_validator!
+        require "lcp_ruby"
+
+        LcpRuby::Types::BuiltInTypes.register_all!
+        LcpRuby::Services::BuiltInAccessors.register_all!
+        LcpRuby::Services::BuiltInTransforms.register_all!
+        LcpRuby::Services::BuiltInDefaults.register_all!
+
+        loader = LcpRuby::Metadata::Loader.new(destination_root_metadata_path)
+        loader.load_all
+
+        result = LcpRuby::Metadata::ConfigurationValidator.new(loader).validate
+        return if result.valid?
+
+        say_status :error, "Generated config failed validation:", :red
+        say result.to_s
+        raise Thor::Error, "ConfigurationValidator reported #{result.errors.size} error(s)."
+      rescue LcpRuby::MetadataError => e
+        raise Thor::Error, "Metadata loading failed during --validate:\n#{e.message}"
+      end
+
+      def destination_root_metadata_path
+        Pathname(destination_root).join("config/lcp_ruby")
+      end
+
+      # Override FormatSupport#dsl_to_yaml: our DSL templates contain ERB and
+      # must be rendered against the generator's binding before DslToYaml can
+      # evaluate them as Ruby. Static templates (gapfree_sequences, etc.)
+      # bypass this path; their dsl_to_yaml reads files verbatim.
+      def dsl_to_yaml(dsl_template)
+        dsl_path = File.join(self.class.source_root, dsl_template)
+        rendered = ERB.new(File.read(dsl_path), trim_mode: "-").result(binding)
+        DslToYaml.convert_string(rendered, virtual_path: dsl_path)
+      end
+    end
+  end
+end