lcp 0.1.0

data/lib/lcp_ruby/metadata/loader.rb

@@ -0,0 +1,916 @@
+require "yaml"
+require "did_you_mean"
+
+module LcpRuby
+  module Metadata
+    class Loader
+      attr_reader :base_path, :model_definitions, :presenter_definitions,
+                  :permission_definitions, :view_group_definitions, :page_definitions,
+                  :menu_definition, :workflow_definitions, :job_definitions,
+                  :abstract_model_names
+
+      def initialize(base_path)
+        @base_path = Pathname.new(base_path)
+        @model_definitions = {}
+        @presenter_definitions = {}
+        @permission_definitions = {}
+        @view_group_definitions = {}
+        @page_definitions = {}
+        @workflow_definitions = {}
+        @job_definitions = {}
+        @menu_definition = nil
+        @sti_builder_hashes = {}
+        @abstract_model_names = []
+        # Memoizes merged permission definitions per model_name. Keyed by
+        # input identity so DB-backed permission_source paths invalidate
+        # naturally: Permissions::Registry.reload! returns a fresh
+        # PermissionDefinition instance after a DB change → object_id
+        # differs → cache miss → recompute. YAML inputs are stable across
+        # the loader's lifetime, so they cache forever (until LcpRuby.reset!
+        # rebuilds the loader).
+        @merged_permission_cache = {}
+      end
+
+      def load_all
+        load_types
+        load_models
+        load_presenters
+        load_pages
+        auto_create_pages
+        warn_unreachable_presenters
+        warn_depends_on_without_action_cable
+        load_permissions
+        load_view_groups
+        validate_references
+        auto_create_view_groups
+        load_menu
+        load_workflows
+        load_jobs
+        load_theme
+      end
+
+      def menu_defined?
+        !@menu_definition.nil?
+      end
+
+      # Returns navigable view groups (those not opted out with navigation: false)
+      def navigable_view_groups
+        @view_group_definitions.values.select(&:navigable?)
+      end
+
+      def load_types
+        load_yamls("types") do |data, file_path|
+          type_data = data["type"] || raise(MetadataError, "Missing 'type' key in #{file_path}")
+          type_def = Types::TypeDefinition.from_hash(type_data)
+          Types::TypeRegistry.register(type_def.name, type_def)
+        end
+
+        load_dsl_types("types")
+      end
+
+      def load_models
+        # Phase 1: Collect raw hashes from YAML and DSL
+        raw_entries = collect_model_hashes
+
+        # Phase 2: Resolve inheritance (merges abstract parents, excludes abstract models)
+        @abstract_model_names = raw_entries.select { |_, e| e[:hash]["abstract"] }.keys
+        resolved = ModelInheritanceResolver.resolve(raw_entries)
+
+        # Phase 3: Create ModelDefinitions from resolved hashes
+        resolved.each do |name, entry|
+          definition = ModelDefinition.from_hash(entry[:hash])
+          definition.source_path = entry[:source_path]
+          definition.source_type = entry[:source_type]
+          @model_definitions[name] = definition
+
+          # Store original child hash for STI children (used by Builder to avoid double-applying)
+          @sti_builder_hashes[name] = entry[:sti_builder_hash] if entry[:sti_builder_hash]
+        end
+      end
+
+      def load_presenters
+        load_yamls("presenters") do |data, file_path|
+          presenter_data = data["presenter"] || raise(MetadataError, "Missing 'presenter' key in #{file_path}")
+          definition = PresenterDefinition.from_hash(presenter_data)
+          set_source!(definition, PathUtils.relative_path(file_path), "yaml")
+          @presenter_definitions[definition.name] = definition
+        end
+
+        load_dsl_presenters("presenters")
+      end
+
+      def load_permissions
+        load_yamls("permissions") do |data, file_path|
+          permission_data = data["permissions"] || raise(MetadataError, "Missing 'permissions' key in #{file_path}")
+          definition = PermissionDefinition.from_hash(permission_data)
+          set_source!(definition, PathUtils.relative_path(file_path), "yaml")
+          @permission_definitions[definition.model] = definition
+        end
+      end
+
+      def load_view_groups
+        @view_group_definitions = {}
+
+        load_yamls("views") do |data, file_path|
+          vg_data = data["view_group"] || raise(MetadataError, "Missing 'view_group' key in #{file_path}")
+          # Inject file-based name if not present
+          vg_data["name"] ||= File.basename(file_path, ".*")
+          definition = ViewGroupDefinition.from_hash({ "view_group" => vg_data })
+          set_source!(definition, PathUtils.relative_path(file_path), "yaml")
+          @view_group_definitions[definition.name] = definition
+        end
+
+        load_dsl_view_groups("views")
+      end
+
+      def view_groups_for_model(model_name)
+        @view_group_definitions.values.select { |vg| vg.model == model_name.to_s }
+      end
+
+      def view_group_for_page(page_name)
+        @view_group_definitions.values.find { |vg| vg.page_names.include?(page_name.to_s) }
+      end
+
+      def model_definition(name)
+        @model_definitions[name.to_s] || raise(MetadataError, "Model '#{name}' not found")
+      end
+
+      def page_definition(name)
+        @page_definitions[name.to_s] || raise(MetadataError, "Page '#{name}' not found")
+      end
+
+      def presenter_definition(name)
+        @presenter_definitions[name.to_s] || raise(MetadataError, "Presenter '#{name}' not found")
+      end
+
+      def presenters_for_model(model_name)
+        @presenter_definitions.values.select { |p| p.model == model_name.to_s }
+      end
+
+      # Returns the merged permission definition for a model: the per-model
+      # definition (resolved through DB→YAML→STI fallback by SourceResolver)
+      # coverage-merged with the `_default` entry. Authors who want full
+      # shadow behavior declare `extends: "none"` on their per-model file.
+      #
+      # See docs/design/permissions_default_role_coverage.md.
+      def permission_definition(model_name)
+        key = model_name.to_s
+        per_model = Permissions::SourceResolver.for(key, self)
+        return per_model unless per_model
+        return per_model if per_model.default?
+        return per_model if per_model.extends == "none"
+
+        default_def = Permissions::SourceResolver.for("_default", self)
+        return per_model unless default_def
+
+        cached = @merged_permission_cache[key]
+        return cached[2] if cached && cached[0].equal?(per_model) && cached[1].equal?(default_def)
+
+        merged = Metadata::PermissionMerger.merge(default: default_def, per_model: per_model)
+        @merged_permission_cache[key] = [ per_model, default_def, merged ]
+        merged
+      end
+
+      def yaml_permission_definition(model_name)
+        perm = @permission_definitions[model_name.to_s]
+        return perm if perm
+
+        # STI child fallback: try parent model permissions
+        model_def = @model_definitions[model_name.to_s]
+        if (parent_name = model_def&.sti_parent_name)
+          perm = @permission_definitions[parent_name]
+          return perm if perm
+        end
+
+        @permission_definitions["_default"]
+      end
+
+      # Returns true iff a non-fallback permission definition exists for this
+      # model. Distinguishes "the configurator wrote a permission file" from
+      # "the lookup chain returned _default."
+      #
+      # Used by the inherits_from validator to confirm parent references point
+      # to real permission files, not phantom names.
+      def has_permission_definition?(model_name)
+        key = model_name.to_s
+        return false if key == "_default"
+        return true if @permission_definitions.key?(key)
+
+        # STI parent fallback (mirror of yaml_permission_definition's logic)
+        model_def = @model_definitions[key]
+        parent_name = model_def&.sti_parent_name
+        !!(parent_name && @permission_definitions.key?(parent_name))
+      end
+
+      # Returns a ModelDefinition built from the original (un-merged) child hash,
+      # suitable for passing to Builder to avoid double-applying parent's
+      # validations/callbacks/enums (which are already inherited via AR class hierarchy).
+      def sti_builder_definition(name)
+        builder_hash = @sti_builder_hashes[name.to_s]
+        return nil unless builder_hash
+
+        full_def = @model_definitions[name.to_s]
+        return nil unless full_def
+
+        # Build a hash with child-only content but with STI metadata
+        child_hash = builder_hash.dup
+        child_hash["table_name"] = full_def.table_name
+        child_hash[ModelInheritanceResolver::STI_CHILD_KEY] = true
+        child_hash["inherits"] = full_def.inherits
+
+        ModelDefinition.from_hash(child_hash)
+      end
+
+    # Merges DB-stored page definitions into the loaded page definitions.
+    # DB pages override YAML pages with the same name.
+    # Auto-pages are recreated after merge to account for newly claimed presenters.
+    # Called from engine boot after Pages::Setup marks the registry available.
+    def merge_db_pages!
+      return unless Pages::Registry.available?
+
+      db_pages = begin
+        Pages::Registry.all_definitions
+      rescue LcpRuby::Error, ActiveRecord::StatementInvalid => e
+        safe_log_warn("[LcpRuby] Failed to load DB page definitions: #{e.message}")
+        raise unless Rails.env.production? if defined?(Rails)
+        return
+      end
+
+      db_pages.each do |db_page|
+        db_page.instance_variable_set(:@source_type, "database")
+        @page_definitions[db_page.name] = db_page
+      end
+
+      # Re-create auto-pages since DB pages may claim presenters that were auto-paged
+      @page_definitions.reject! { |_, p| p.auto_generated? }
+      auto_create_pages
+
+      # Clear resolver cache since pages changed
+      Pages::Resolver.clear!
+    end
+
+    def unreachable_presenter_names
+      used_in_zones = Set.new
+      @page_definitions.each_value do |page|
+        next if page.auto_generated?
+        page.zones.each { |z| used_in_zones << z.presenter if z.presenter_zone? }
+        used_in_zones << page.index_presenter if page.index_presenter
+      end
+
+      @presenter_definitions.each_value.filter_map do |presenter|
+        auto_page = @page_definitions[presenter.name]
+        next unless auto_page&.auto_generated?
+        next if auto_page.routable?
+        next if used_in_zones.include?(presenter.name)
+        next if auto_page.dialog_only?
+
+        presenter.name
+      end
+    end
+
+    private
+
+      # Defensive Rails.logger wrappers — `Rails` is not always defined (gem
+      # loaded outside Rails) and `Rails.logger` can be nil during very early
+      # boot. All metadata loader logging goes through these.
+      def safe_log_warn(message)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      end
+
+      def safe_log_info(message)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.info(message)
+      end
+
+      def warn_unreachable_presenters
+        unreachable_presenter_names.each do |name|
+          safe_log_warn("[LcpRuby] Presenter '#{name}' is unreachable: " \
+                        "no slug, not used in any page zone, and not dialog-only")
+        end
+      end
+
+      def warn_depends_on_without_action_cable
+        return if defined?(ActionCable)
+
+        pages_with_deps = @page_definitions.values.select { |p| p.zones.any?(&:depends_on?) }
+        return if pages_with_deps.empty?
+
+        names = pages_with_deps.map(&:name).join(", ")
+        safe_log_warn("[LcpRuby] Pages with depends_on zones (#{names}) detected, " \
+                      "but ActionCable is not available. Auto-refresh disabled; " \
+                      "use reload_zones for manual refresh.")
+      end
+
+      def load_pages
+        @page_definitions = {}
+
+        load_yamls("pages") do |data, file_path|
+          page_data = data["page"] || raise(MetadataError, "Missing 'page' key in #{file_path}")
+          relative_path = PathUtils.relative_path(file_path)
+          definition =
+            begin
+              PageDefinition.from_hash(page_data)
+            rescue MetadataError => e
+              # Re-raise with the source file path appended so the
+              # configurator can locate the offending YAML. Catches ANY
+              # MetadataError surfaced by `from_hash` — FilterFormValidator
+              # shape rules, `validate!` (name/zones/layout), or zone
+              # construction. PageDefinition.from_hash itself cannot
+              # embed source_path (Ruby 3 kwarg-separation collision
+              # with string-keyed hash literal callers). Preserve the
+              # original backtrace so debugging lands on the validator
+              # method, not this rescue line.
+              raise MetadataError, "#{e.message} (in #{relative_path})", e.backtrace
+            end
+          set_source!(definition, relative_path, "yaml")
+          @page_definitions[definition.name] = definition
+        end
+      end
+
+      def auto_create_pages
+        # Collect presenter names already claimed by explicit pages (presenter zones only)
+        claimed_presenters = Set.new
+        @page_definitions.each_value do |page|
+          page.zones.each { |z| claimed_presenters << z.presenter if z.presenter_zone? }
+        end
+
+        @presenter_definitions.each_value do |presenter|
+          next if claimed_presenters.include?(presenter.name)
+          next if @page_definitions.key?(presenter.name)
+
+          zone = ZoneDefinition.new(name: "main", presenter: presenter.name)
+          page = PageDefinition.new(
+            name: presenter.name,
+            model: presenter.model,
+            slug: presenter.slug,
+            dialog_config: presenter.dialog_config,
+            zones: [ zone ],
+            auto_generated: true,
+            source_type: "auto"
+          )
+          @page_definitions[page.name] = page
+        end
+      end
+
+      def set_source!(definition, path, type)
+        definition.source_path = path
+        definition.source_type = type
+      end
+
+      def load_yamls(subdirectory)
+        dir = base_path.join(subdirectory)
+        return unless dir.exist?
+
+        Dir[dir.join("*.yml"), dir.join("*.yaml")].sort.each do |file_path|
+          data = YAML.safe_load_file(file_path, permitted_classes: [ Symbol, Regexp ])
+          next unless data
+
+          yield(data, file_path)
+        rescue Psych::SyntaxError => e
+          raise MetadataError, "YAML syntax error in #{file_path}: #{e.message}"
+        end
+      end
+
+      def load_dsl_types(subdirectory)
+        dir = base_path.join(subdirectory)
+        Dsl::DslLoader.load_types(dir).each do |name, type_def|
+          if Types::TypeRegistry.registered?(name)
+            raise MetadataError,
+              "Duplicate type '#{name}' — already loaded, conflict in DSL files"
+          end
+          Types::TypeRegistry.register(name, type_def)
+        end
+      end
+
+      def collect_model_hashes
+        raw_entries = {}
+
+        # Collect from YAML files
+        load_yamls("models") do |data, file_path|
+          model_data = data["model"] || raise(MetadataError, "Missing 'model' key in #{file_path}")
+          name = model_data["name"]&.to_s
+          raise MetadataError, "Model in #{file_path} is missing 'name'" unless name.present?
+
+          if raw_entries.key?(name)
+            raise MetadataError, "Duplicate model '#{name}' — already loaded, conflict at #{file_path}"
+          end
+
+          raw_entries[name] = {
+            hash: model_data,
+            source_path: PathUtils.relative_path(file_path),
+            source_type: "yaml"
+          }
+        end
+
+        # Collect from DSL files
+        dir = base_path.join("models")
+        dsl_entries = Dsl::DslLoader.load_model_hashes(dir)
+        dsl_entries.each do |name, entry|
+          if raw_entries.key?(name)
+            raise MetadataError,
+              "Duplicate model '#{name}' — already loaded, conflict in DSL files"
+          end
+          raw_entries[name] = entry
+        end
+
+        raw_entries
+      end
+
+      def load_dsl_presenters(subdirectory)
+        dir = base_path.join(subdirectory)
+        dsl_definitions = Dsl::DslLoader.load_presenters(dir)
+        dsl_definitions.each do |name, definition|
+          register_presenter_definition!(definition, dir.join("#{name}.rb"))
+        end
+      end
+
+      def register_presenter_definition!(definition, source_path)
+        if @presenter_definitions.key?(definition.name)
+          raise MetadataError,
+            "Duplicate presenter '#{definition.name}' — already loaded, conflict at #{source_path}"
+        end
+        @presenter_definitions[definition.name] = definition
+      end
+
+      def register_view_group_definition!(definition, source_path)
+        if @view_group_definitions.key?(definition.name)
+          raise MetadataError,
+            "Duplicate view group '#{definition.name}' — already loaded, conflict at #{source_path}"
+        end
+        @view_group_definitions[definition.name] = definition
+      end
+
+      def load_dsl_view_groups(subdirectory)
+        dir = base_path.join(subdirectory)
+        dsl_definitions = Dsl::DslLoader.load_view_groups(dir)
+        dsl_definitions.each do |name, definition|
+          register_view_group_definition!(definition, dir.join("#{name}.rb"))
+        end
+      end
+
+      # Auto-registered view groups land in the 900–999 position tier so they
+      # never collide with user-defined positions (which conventionally use 0–899).
+      AUTO_VIEW_GROUP_POSITION_BASE = 900
+
+      def auto_create_view_groups
+        # Group routable pages by model
+        pages_by_model = {}
+        standalone_pages = []
+
+        @page_definitions.each_value do |page|
+          next unless page.routable?
+
+          if page.standalone?
+            standalone_pages << page
+          else
+            model_name = page.model
+            next unless model_name
+            (pages_by_model[model_name] ||= []) << page
+          end
+        end
+
+        # Collect specs first; second pass sorts by name and assigns positions
+        # so order is deterministic across boots regardless of file load order.
+        specs = []
+
+        pages_by_model.each do |model_name, pages|
+          # Skip if an explicit view group already covers this model
+          next if view_groups_for_model(model_name).any?
+          # Only auto-create if exactly one routable page for this model
+          next unless pages.length == 1
+
+          page = pages.first
+          presenter = @presenter_definitions[page.main_presenter_name]
+          next unless presenter
+
+          specs << {
+            name: model_name,
+            model: model_name,
+            primary_page: page.name,
+            menu_position: presenter.menu_position,
+            presenter_name: presenter.name,
+            views: [ { "page" => page.name, "label" => presenter.label } ],
+            log: "Auto-created view group for model '#{model_name}' with page '#{page.name}'"
+          }
+        end
+
+        # Auto-create view groups for standalone pages not referenced by any VG
+        all_vg_pages = Set.new(@view_group_definitions.values.flat_map(&:page_names))
+        standalone_pages.each do |page|
+          next if all_vg_pages.include?(page.name)
+
+          specs << {
+            name: page.name,
+            model: nil,
+            primary_page: page.name,
+            menu_position: nil,
+            views: [ { "page" => page.name, "label" => page.title } ],
+            log: "Auto-created view group for standalone page '#{page.name}'"
+          }
+        end
+
+        specs.sort_by! { |spec| spec[:name] }
+        specs.each_with_index do |spec, index|
+          # Collision check: explicit YAML/DSL view groups are loaded first
+          # (load_view_groups in load_all), so any clash here means a user
+          # named a view group identically to the model/page it covers
+          # without binding it (otherwise view_groups_for_model would have
+          # skipped this spec). Raise eagerly with a hint instead of silently
+          # overwriting — silent overwrite was a latent bug masked by the
+          # former `_auto` suffix.
+          if @view_group_definitions.key?(spec[:name])
+            raise MetadataError,
+              "Auto-created view group '#{spec[:name]}' collides with an existing view group. " \
+              "Bind the explicit view group to model '#{spec[:model] || '(none)'}' " \
+              "(add `model: #{spec[:model]}` so it claims the auto-create slot), " \
+              "or rename one of them."
+          end
+
+          # #15 — presenter-level `menu_position:` lifts a single-presenter model
+          # out of the alphabetical 900+index tier without forcing a full
+          # view-group YAML. nil → fall back to the default tier.
+          position = spec[:menu_position] || (AUTO_VIEW_GROUP_POSITION_BASE + index)
+
+          # D4 §"`presenter.menu_position` deprecation warning" — only fires
+          # when the presenter actually used the override AND we created the
+          # auto-VG (so the override has effect). Dedup'd per presenter name
+          # so dev autoreload does not spam. Behavior unchanged in v1; this
+          # is a wording + telemetry surface so configurators learn to write
+          # menu.yml before v2 promotes to :warning and removes the field.
+          if spec[:menu_position] && spec[:presenter_name]
+            @menu_position_warned ||= Set.new
+            unless @menu_position_warned.include?(spec[:presenter_name])
+              @menu_position_warned << spec[:presenter_name]
+              safe_log_info(
+                "[LcpRuby] Presenter '#{spec[:presenter_name]}' uses `menu_position:` " \
+                "to control auto-append order for view group '#{spec[:name]}'. " \
+                "This is a deprecated workaround — write config/lcp_ruby/menu.yml " \
+                "for explicit menu order. `menu_position` will be removed in a future release."
+              )
+            end
+          end
+
+          vg = ViewGroupDefinition.new(
+            name: spec[:name],
+            model: spec[:model],
+            primary_page: spec[:primary_page],
+            navigation_config: { "menu" => "main", "position" => position },
+            views: spec[:views],
+            source_type: "auto"
+          )
+          @view_group_definitions[vg.name] = vg
+
+          safe_log_info(spec[:log])
+        end
+      end
+
+      def load_workflows
+        @workflow_definitions = {}
+
+        load_yamls("workflows") do |data, file_path|
+          wf_data = data["workflow"] || raise(MetadataError, "Missing 'workflow' key in #{file_path}")
+          definition = Workflow::WorkflowDefinition.from_hash(wf_data)
+          set_source!(definition, PathUtils.relative_path(file_path), "yaml")
+
+          if @workflow_definitions.key?(definition.name)
+            raise MetadataError, "Duplicate workflow '#{definition.name}' — conflict at #{file_path}"
+          end
+
+          validate_workflow_reference!(definition)
+          @workflow_definitions[definition.name] = definition
+        end
+
+        load_dsl_workflows("workflows")
+      end
+
+      def load_dsl_workflows(subdirectory)
+        dir = base_path.join(subdirectory)
+        dsl_definitions = Dsl::DslLoader.load_workflows(dir)
+        dsl_definitions.each do |name, definition|
+          if @workflow_definitions.key?(name)
+            raise MetadataError,
+              "Duplicate workflow '#{name}' — already loaded, conflict in DSL files"
+          end
+
+          validate_workflow_reference!(definition)
+          @workflow_definitions[name] = definition
+        end
+      end
+
+      def validate_workflow_reference!(definition)
+        unless @model_definitions.key?(definition.model)
+          raise MetadataError, "Workflow '#{definition.name}' references unknown model '#{definition.model}'"
+        end
+
+        model_def = @model_definitions[definition.model]
+        enum_field = model_def.enum_fields.find { |f| f.name == definition.field }
+        unless enum_field
+          raise MetadataError, "Workflow '#{definition.name}': field '#{definition.field}' " \
+                               "is not an enum field on model '#{definition.model}'"
+        end
+      end
+
+      def load_jobs
+        @job_definitions = {}
+
+        load_yamls("jobs") do |data, file_path|
+          job_data = data["job"] || raise(MetadataError, "Missing 'job' key in #{file_path}")
+          definition = BackgroundJobs::Definition.from_hash(job_data)
+          definition.source_path = PathUtils.relative_path(file_path)
+          definition.source_type = "yaml"
+
+          if @job_definitions.key?(definition.name)
+            raise MetadataError, "Duplicate job '#{definition.name}' — conflict at #{file_path}"
+          end
+
+          @job_definitions[definition.name] = definition
+        end
+
+        load_dsl_jobs("jobs")
+      end
+
+      def load_dsl_jobs(subdirectory)
+        dir = base_path.join(subdirectory)
+        dsl_definitions = Dsl::DslLoader.load_jobs(dir)
+        dsl_definitions.each do |name, definition|
+          if @job_definitions.key?(name)
+            raise MetadataError,
+              "Duplicate job '#{name}' — already loaded, conflict in DSL files"
+          end
+
+          @job_definitions[name] = definition
+        end
+      end
+
+      def validate_references
+        @presenter_definitions.each_value do |presenter|
+          unless @model_definitions.key?(presenter.model)
+            if @abstract_model_names.include?(presenter.model)
+              raise MetadataError,
+                "Presenter '#{presenter.name}' references abstract model '#{presenter.model}'. " \
+                "Abstract models cannot have presenters — use a concrete model that inherits from it."
+            else
+              raise MetadataError,
+                "Presenter '#{presenter.name}' references unknown model '#{presenter.model}'"
+            end
+          end
+        end
+
+        validate_view_group_references
+      end
+
+      def validate_view_group_references
+        page_in_groups = {}
+
+        @view_group_definitions.each_value do |vg|
+          if vg.model.present? && !@model_definitions.key?(vg.model)
+            raise MetadataError,
+              "View group '#{vg.name}' references unknown model '#{vg.model}'"
+          end
+
+          vg.page_names.each do |pname|
+            unless @page_definitions.key?(pname)
+              raise MetadataError,
+                "View group '#{vg.name}' references unknown page '#{pname}'"
+            end
+
+            if page_in_groups.key?(pname)
+              raise MetadataError,
+                "Page '#{pname}' appears in multiple view groups: '#{page_in_groups[pname]}' and '#{vg.name}'"
+            end
+            page_in_groups[pname] = vg.name
+          end
+        end
+      end
+
+      def load_menu
+        menu_mode = LcpRuby.configuration.menu_mode
+        menu_file = find_menu_file
+
+        if menu_mode == :strict
+          validate_strict_mode!
+          unless menu_file
+            raise MetadataError, "menu.yml is required when menu_mode is :strict"
+          end
+        end
+
+        unless menu_file
+          log_auto_menu_hint_if_no_menu_yml if menu_mode == :auto
+          return
+        end
+
+        data = YAML.safe_load_file(menu_file, permitted_classes: [ Symbol, Regexp ])
+        return unless data
+
+        @menu_definition = MenuDefinition.from_hash(data)
+        validate_menu_references!
+
+        auto_append_unreferenced_view_groups! if menu_mode == :auto
+      rescue Psych::SyntaxError => e
+        raise MetadataError, "YAML syntax error in #{menu_file}: #{e.message}"
+      end
+
+      def load_theme
+        theme_file = %w[theme.yml theme.yaml].map { |f| base_path.join(f) }.find(&:exist?)
+        return unless theme_file
+
+        data = YAML.safe_load_file(theme_file, permitted_classes: [ Symbol, Regexp ])
+        return unless data.is_a?(Hash) && data["theme"].is_a?(Hash)
+
+        theme_data = data["theme"]
+        config = LcpRuby.configuration.theme
+
+        if (val = theme_data["default"])
+          config[:default] = coerce_theme_symbol(theme_file, "default", val)
+        end
+        config[:allow_user_switch] = theme_data["allow_user_switch"] unless theme_data["allow_user_switch"].nil?
+
+        if (density = ensure_theme_hash!(theme_file, "density", theme_data["density"]))
+          if (val = density["default"])
+            config[:density][:default] = coerce_theme_symbol(theme_file, "density.default", val)
+          end
+        end
+
+        if (br = ensure_theme_hash!(theme_file, "border_radius", theme_data["border_radius"]))
+          if (val = br["default"])
+            config[:border_radius][:default] = coerce_theme_symbol(theme_file, "border_radius.default", val)
+          end
+        end
+
+        if (overrides = ensure_theme_hash!(theme_file, "overrides", theme_data["overrides"]))
+          config[:overrides] = overrides
+        end
+
+        if (palettes = ensure_theme_hash!(theme_file, "palettes", theme_data["palettes"]))
+          config[:palettes] = palettes.transform_keys(&:to_sym)
+        end
+      rescue Psych::SyntaxError => e
+        raise MetadataError, "YAML syntax error in #{theme_file}: #{e.message}"
+      end
+
+      def ensure_theme_hash!(file, key_path, val)
+        return nil if val.nil?
+        unless val.is_a?(Hash)
+          raise MetadataError, "#{file}: '#{key_path}' must be a hash, got #{val.class}"
+        end
+        val
+      end
+
+      def coerce_theme_symbol(file, key_path, val)
+        unless val.is_a?(String) || val.is_a?(Symbol)
+          raise MetadataError, "#{file}: '#{key_path}' must be a string, got #{val.class}"
+        end
+        val.to_sym
+      end
+
+      def find_menu_file
+        %w[menu.yml menu.yaml].each do |filename|
+          path = base_path.join(filename)
+          return path if path.exist?
+        end
+        nil
+      end
+
+      def validate_strict_mode!
+        @view_group_definitions.each_value do |vg|
+          next unless vg.navigable?
+
+          nav = vg.navigation_config
+          if nav.is_a?(Hash) && nav.any?
+            raise MetadataError,
+              "View group '#{vg.name}' has navigation config but menu_mode is :strict. " \
+              "Use navigation: false or remove navigation config."
+          end
+        end
+      end
+
+      def validate_menu_references!
+        validate_menu_items!(@menu_definition.top_menu) if @menu_definition.has_top_menu?
+        validate_menu_items!(@menu_definition.sidebar_menu) if @menu_definition.has_sidebar_menu?
+      end
+
+      def validate_menu_items!(items)
+        items.each do |item|
+          canonicalize_view_group_ref!(item) if item.view_group?
+          validate_menu_items!(item.children) if item.group?
+        end
+      end
+
+      # Validates a menu `view_group:` reference. Auto-created view groups
+      # share the same name as their model (or standalone page) — no suffix
+      # rewriting needed. On a genuine miss, raise with a `did_you_mean` hint.
+      def canonicalize_view_group_ref!(item)
+        name = item.view_group_name
+        return if @view_group_definitions.key?(name)
+
+        available = @view_group_definitions.keys.sort
+        suggestion = DidYouMean::SpellChecker.new(dictionary: available).correct(name).first
+        hint = suggestion ? " Did you mean '#{suggestion}'?" : ""
+        raise MetadataError,
+          "Menu references unknown view group '#{name}'.#{hint} " \
+          "Available: #{available.join(', ')}"
+      end
+
+      # In :auto mode, append navigable view groups not referenced in menu.yml.
+      # Skips view groups that have opted out via navigation: { auto_append: false }
+      # (typically infrastructure view groups like audit_logs, job_executions).
+      # Also skips auto-VGs when a peer VG for the same model is already
+      # referenced in menu.yml under a different name (D4 §"B59 cross-presenter
+      # auto-append dedup"): auto-create runs before menu.yml is loaded so it
+      # cannot know which explicit VGs the user wired into navigation.
+      def auto_append_unreferenced_view_groups!
+        referenced = collect_referenced_view_groups(@menu_definition)
+
+        unreferenced = navigable_view_groups
+                         .select(&:auto_append?)
+                         .reject { |vg| referenced.include?(vg.name) }
+                         .reject do |vg|
+                           next false unless vg.source_type == "auto" && vg.model
+                           view_groups_for_model(vg.model).any? do |peer|
+                             peer.name != vg.name && referenced.include?(peer.name)
+                           end
+                         end
+        return if unreferenced.empty?
+
+        sorted = unreferenced.sort_by do |vg|
+          nav = vg.navigation_config
+          nav.is_a?(Hash) ? (nav["position"] || 99) : 99
+        end
+
+        # Auto-appended items have no YAML site. When the primary
+        # presenter resolves a label, MenuItem#resolved_label uses it;
+        # otherwise the loader IS the authoring site and synthesises a
+        # humanised label so the item passes content-driven validation.
+        appended_items = sorted.map do |vg|
+          page = page_definitions[vg.primary_page]
+          presenter = page && presenter_definitions[page.main_presenter_name]
+          if presenter&.resolved_label.present?
+            MenuItem.new(type: :view_group, view_group_name: vg.name)
+          else
+            MenuItem.new(type: :view_group, view_group_name: vg.name, label: vg.name.humanize)
+          end
+        end
+
+        # Append to top_menu (create it if only sidebar exists)
+        if @menu_definition.has_top_menu?
+          @menu_definition = MenuDefinition.new(
+            top_menu: @menu_definition.top_menu + appended_items,
+            sidebar_menu: @menu_definition.sidebar_menu
+          )
+        else
+          @menu_definition = MenuDefinition.new(
+            top_menu: appended_items,
+            sidebar_menu: @menu_definition.sidebar_menu
+          )
+        end
+
+        # D4 §"Auto-append transparency log" — surface auto-appends so the
+        # configurator can see what got auto-placed without having to click
+        # around the UI to discover it. Info-level (intended default behavior,
+        # not a smell). Complements `log_auto_menu_hint_if_no_menu_yml`
+        # (mutually exclusive trigger: that one fires only when no menu.yml
+        # exists; this one fires only when menu.yml exists AND we appended).
+        names = appended_items.map(&:view_group_name).join(", ")
+        safe_log_info(
+          "[LcpRuby] Auto-appended #{appended_items.size} view groups to top_menu: #{names}. " \
+          "Add them to config/lcp_ruby/menu.yml for custom ordering or dropdown placement, " \
+          "or set `navigation: { auto_append: false }` on the view group to hide it from the menu."
+        )
+      end
+
+      def log_auto_menu_hint_if_no_menu_yml
+        view_groups = navigable_view_groups.select(&:auto_append?)
+        return if view_groups.size < 5
+
+        # Only nudge when the user has not customized any view group — i.e. every
+        # navigable group is auto-generated (source_type "auto"). Once the user
+        # writes a `views/<name>.yml` or a DSL `views/<name>.rb`, they're managing
+        # menu order on purpose.
+        return unless view_groups.all? { |vg| vg.source_type == "auto" }
+
+        safe_log_info(
+          "[LcpRuby] Auto-menu has #{view_groups.size} view groups in default (alphabetical) order, " \
+          "no config/lcp_ruby/menu.yml. " \
+          "To control order: add `navigation: { position: N }` to a view-group YAML in config/lcp_ruby/views/. " \
+          "To customize structure: create config/lcp_ruby/menu.yml. " \
+          "See docs/guides/menu.md."
+        )
+      end
+
+      def collect_referenced_view_groups(menu_def)
+        names = Set.new
+        collect_vg_names(menu_def.top_menu || [], names)
+        collect_vg_names(menu_def.sidebar_menu || [], names)
+        names
+      end
+
+      def collect_vg_names(items, names)
+        items.each do |item|
+          names << item.view_group_name if item.view_group?
+          collect_vg_names(item.children, names) if item.group?
+        end
+      end
+    end
+  end
+end