iron-cms 0.17.2 → 0.18.0

data/app/models/iron/schema/diff.rb

@@ -0,0 +1,194 @@
+module Iron
+  class Schema::Diff
+    PRUNE_HINT = "[in database, not in file — PRUNE=1 deletes]"
+    SET_ATTRIBUTES = %i[supported_block_definitions supported_content_types].freeze
+
+    attr_reader :notes
+
+    def initialize(schema)
+      @schema = schema
+      @notes = []
+      snapshot
+    end
+
+    def to_h
+      {
+        locales: @locales,
+        block_definitions: @block_definitions,
+        content_types: @content_types,
+        notes: notes
+      }
+    end
+
+    def empty?
+      sections.all? { |section| section.values.all?(&:empty?) }
+    end
+
+    # Removals are only applied in prune mode, so the apply task excludes them
+    # from its applied-changes count while still listing them as candidates.
+    def size(include_removals: true)
+      buckets = include_removals ? %i[add update remove] : %i[add update]
+      sections.sum { |section| section.values_at(*buckets).sum(&:size) }
+    end
+
+    def removals
+      {
+        locales: @locales[:remove],
+        block_definitions: @block_definitions[:remove],
+        content_types: @content_types[:remove],
+        block_definition_fields: field_removals(@block_definitions),
+        content_type_fields: field_removals(@content_types)
+      }
+    end
+
+    def add_note(note)
+      notes << note
+    end
+
+    def to_s
+      return "Schema is in sync." if empty?
+
+      lines = []
+      lines.concat(section_lines("locales", @locales))
+      lines.concat(section_lines("block_definitions", @block_definitions))
+      lines.concat(section_lines("content_types", @content_types))
+      lines.concat(notes.map { |note| "note: #{note}" })
+      lines.join("\n")
+    end
+
+    private
+
+      attr_reader :schema
+
+      def sections
+        [ @locales, @block_definitions, @content_types ]
+      end
+
+      # The diff is a snapshot: apply builds it before importing so it reports
+      # what is about to change rather than the post-import state.
+      def snapshot
+        @locales = diff_locales
+        @block_definitions = diff_schemables(schema[:block_definitions] || [], BlockDefinition.order(:handle))
+        @content_types = diff_schemables(schema[:content_types] || [], ContentType.order(:handle))
+      end
+
+      def diff_locales
+        file_locales = schema[:locales] || []
+        file_codes = file_locales.map { |attrs| attrs[:code].to_s }
+        db_by_code = Locale.order(:code).index_by(&:code)
+
+        {
+          add: file_codes - db_by_code.keys,
+          update: file_locales.filter_map { |attrs| renamed_locale_code(attrs, db_by_code[attrs[:code].to_s]) },
+          remove: db_by_code.keys - file_codes
+        }
+      end
+
+      def renamed_locale_code(attrs, locale)
+        attrs[:code].to_s if locale && attrs[:name].present? && attrs[:name].to_s != locale.name
+      end
+
+      def diff_schemables(file_list, db_scope)
+        db_by_handle = db_scope.index_by(&:handle)
+        file_handles = file_list.map { |attrs| attrs[:handle].to_s }
+
+        {
+          add: file_handles - db_by_handle.keys,
+          update: file_list.filter_map { |attrs| schemable_update(attrs, db_by_handle[attrs[:handle].to_s]) },
+          remove: db_by_handle.keys - file_handles
+        }
+      end
+
+      def schemable_update(attrs, record)
+        return unless record
+
+        changed = changed_attribute_names(attrs, record.export_attributes)
+        fields = diff_field_definitions(attrs[:field_definitions] || [], record)
+        reorder = reorder?(attrs[:field_definitions] || [], record)
+        return if changed.empty? && fields.values.all?(&:empty?) && !reorder
+
+        { handle: record.handle, changed:, fields:, reorder: }
+      end
+
+      def diff_field_definitions(file_fields, record)
+        db_by_handle = record.field_definitions.index_by(&:handle)
+        file_handles = file_fields.map { |attrs| attrs[:handle].to_s }
+
+        {
+          add: file_fields.reject { |attrs| db_by_handle.key?(attrs[:handle].to_s) }
+                          .map { |attrs| { handle: attrs[:handle].to_s, type: attrs[:type].to_s } },
+          update: file_fields.filter_map { |attrs| field_update(attrs, db_by_handle[attrs[:handle].to_s]) },
+          remove: db_by_handle.keys - file_handles
+        }
+      end
+
+      def field_update(attrs, definition)
+        return unless definition
+
+        changed = changed_attribute_names(attrs, definition.export_attributes)
+        { handle: definition.handle, changed: } if changed.any?
+      end
+
+      def reorder?(file_fields, record)
+        file_handles = file_fields.map { |attrs| attrs[:handle].to_s }
+        db_handles = record.field_definitions.map(&:handle)
+
+        (db_handles & file_handles) != (file_handles & db_handles)
+      end
+
+      def changed_attribute_names(file_attrs, db_attrs)
+        file_side = normalize(file_attrs)
+        db_side = normalize(db_attrs)
+
+        (file_side.keys | db_side.keys).select { |key| file_side[key] != db_side[key] }
+      end
+
+      # Schema files omit ranks (array order rules) and false booleans, so both
+      # sides are compacted the same way before comparison. Supported handles
+      # are sets: the import cannot honor their order.
+      def normalize(attrs)
+        attrs
+          .deep_symbolize_keys
+          .except(:rank, :field_definitions)
+          .to_h { |key, value| [ key, normalize_value(key, value) ] }
+          .compact_blank
+      end
+
+      def normalize_value(key, value)
+        case value
+        when Hash then value.compact_blank
+        when Array then SET_ATTRIBUTES.include?(key) ? value.sort : value
+        else value
+        end
+      end
+
+      def field_removals(section)
+        section[:update].each_with_object({}) do |entry, removals|
+          removals[entry[:handle]] = entry[:fields][:remove] if entry[:fields][:remove].any?
+        end
+      end
+
+      def section_lines(title, section)
+        return [] if section.values.all?(&:empty?)
+
+        [ "#{title}:" ].tap do |lines|
+          section[:add].each { |handle| lines << "  + #{handle}" }
+          section[:update].each { |entry| lines.concat(entry.is_a?(Hash) ? update_lines(entry) : [ "  ~ #{entry}" ]) }
+          section[:remove].each { |handle| lines << "  - #{handle} #{PRUNE_HINT}" }
+        end
+      end
+
+      def update_lines(entry)
+        [ "  ~ #{entry[:handle]}#{attribute_list(entry[:changed])}" ].tap do |lines|
+          entry[:fields][:add].each { |field| lines << "      + field #{field[:handle]} (#{field[:type]})" }
+          entry[:fields][:update].each { |field| lines << "      ~ field #{field[:handle]}#{attribute_list(field[:changed])}" }
+          entry[:fields][:remove].each { |handle| lines << "      - field #{handle} #{PRUNE_HINT}" }
+          lines << "      ~ field order changed" if entry[:reorder]
+        end
+      end
+
+      def attribute_list(changed)
+        changed.any? ? " (#{changed.join(', ')})" : ""
+      end
+  end
+end

data/app/models/iron/schema/validation.rb

@@ -0,0 +1,214 @@
+module Iron
+  class Schema::Validation
+    HANDLE_FORMAT = /\A[a-z0-9_]+\z/
+
+    # In prune mode, objects in the database but not in the file are about to
+    # be destroyed, so only file-declared handles count as known.
+    def initialize(schema, prune: false)
+      @schema = schema
+      @prune = prune
+      @problems = []
+    end
+
+    def problems
+      validate_locales
+      validate_block_definitions
+      validate_content_types
+      @problems
+    end
+
+    private
+
+      attr_reader :schema
+
+      def flag(problem)
+        @problems << problem
+      end
+
+      def validate_locales
+        seen_codes = Set.new
+        (schema[:locales] || []).each_with_index do |attrs, index|
+          context = "locales[#{index}]"
+          next flag "#{context}: must be an object" unless attrs.is_a?(Hash)
+
+          flag "#{context}: code is required" if attrs[:code].blank?
+          flag "#{context}: name is required" if attrs[:name].blank?
+          flag_duplicate(seen_codes, attrs[:code], "code", context)
+        end
+      end
+
+      def validate_block_definitions
+        seen_handles = Set.new
+        (schema[:block_definitions] || []).each_with_index do |attrs, index|
+          context = "block_definitions[#{index}]"
+          next flag "#{context}: must be an object" unless attrs.is_a?(Hash)
+
+          validate_handle(attrs[:handle], context)
+          flag_duplicate(seen_handles, attrs[:handle], "handle", context)
+          flag "#{context}: name is required" if attrs[:name].blank?
+          validate_field_definitions(attrs, context)
+        end
+      end
+
+      def validate_content_types
+        seen_handles = Set.new
+        (schema[:content_types] || []).each_with_index do |attrs, index|
+          context = "content_types[#{index}]"
+          next flag "#{context}: must be an object" unless attrs.is_a?(Hash)
+
+          validate_handle(attrs[:handle], context)
+          flag_duplicate(seen_handles, attrs[:handle], "handle", context)
+          flag "#{context}: name is required" if attrs[:name].blank?
+          validate_content_type_type(attrs[:type], context)
+          validate_icon(attrs[:icon], context)
+          validate_field_definitions(attrs, context)
+        end
+      end
+
+      def validate_content_type_type(type, context)
+        return if %w[single collection].include?(type.to_s)
+
+        flag %(#{context}: unknown type "#{type}" (valid: single, collection))
+      end
+
+      def validate_icon(icon, context)
+        return if icon.blank?
+        return if IconCatalog.all.empty? || IconCatalog.include?(icon.to_s)
+
+        flag %(#{context}: unknown icon "#{icon}" (icons are Lucide names — Iron::IconCatalog.all lists the valid set))
+      end
+
+      def validate_field_definitions(owner_attrs, owner_context)
+        seen_handles = Set.new
+        (owner_attrs[:field_definitions] || []).each_with_index do |attrs, index|
+          context = "#{owner_context}.field_definitions[#{index}]"
+          next flag "#{context}: must be an object" unless attrs.is_a?(Hash)
+
+          validate_field_handle(attrs[:handle], context)
+          flag_duplicate(seen_handles, attrs[:handle], "handle", context)
+          flag "#{context}: name is required" if attrs[:name].blank?
+          validate_field_type(attrs, context)
+          validate_field_metadata(attrs, context)
+        end
+      end
+
+      def flag_duplicate(seen, value, label, context)
+        return if value.blank?
+
+        flag %(#{context}: duplicate #{label} "#{value}") unless seen.add?(value.to_s)
+      end
+
+      def validate_field_handle(handle, context)
+        validate_handle(handle, context)
+        flag %(#{context}: handle "#{handle}" is reserved) if FieldDefinition::RESERVED_HANDLES.include?(handle.to_s)
+      end
+
+      def validate_handle(handle, context)
+        if handle.blank?
+          flag "#{context}: handle is required"
+        elsif !handle.to_s.match?(HANDLE_FORMAT)
+          flag %(#{context}: handle "#{handle}" must contain only lowercase letters, numbers and underscores)
+        end
+      end
+
+      def validate_field_type(attrs, context)
+        type = attrs[:type].to_s
+        return flag %(#{context}: unknown type "#{type}" (valid: #{FieldDefinition::TYPES.join(', ')})) unless FieldDefinition::TYPES.include?(type)
+
+        case type
+        when "block"
+          supported = Array(attrs[:supported_block_definitions])
+          flag "#{context}: block fields must list exactly one supported_block_definitions handle" unless supported.size == 1
+          validate_known_block_definitions(supported, context)
+        when "block_list"
+          validate_known_block_definitions(Array(attrs[:supported_block_definitions]), context)
+        when "reference", "reference_list"
+          validate_known_content_types(Array(attrs[:supported_content_types]), context)
+        end
+      end
+
+      def validate_field_metadata(attrs, context)
+        type_handle = attrs[:type].to_s
+        return unless FieldDefinition::TYPES.include?(type_handle)
+
+        metadata = attrs[:metadata]
+        return if metadata.nil?
+        return flag "#{context}: metadata must be an object" unless metadata.is_a?(Hash)
+
+        metadata = metadata.transform_keys(&:to_s)
+        flag_unknown_metadata_keys(type_handle, metadata, context)
+        flag_unrestricted_specific_scope(type_handle, metadata, context)
+        FieldDefinition::Validations.violations(type_handle, metadata).each do |violation|
+          flag metadata_violation(violation, context)
+        end
+      end
+
+      def metadata_violation(violation, context)
+        return "#{context}: #{violation.message}" if violation.attribute == :metadata
+
+        "#{context}: metadata.#{violation.attribute} #{violation.message}"
+      end
+
+      def flag_unknown_metadata_keys(type_handle, metadata, context)
+        known = known_metadata_keys(type_handle)
+        (metadata.keys - FieldDefinition::Validations::RULES.keys - known).each do |key|
+          flag "#{context}: #{unknown_metadata_key_message(key, type_handle, known)}"
+        end
+      end
+
+      def unknown_metadata_key_message(key, type_handle, known)
+        return %(unknown metadata key "#{key}" for #{type_handle} (#{type_handle} supports no metadata keys)) if known.empty?
+
+        %(unknown metadata key "#{key}" for #{type_handle} (known: #{known.join(', ')}))
+      end
+
+      def known_metadata_keys(type_handle)
+        klass = FieldDefinition.classify_type(type_handle).constantize
+        keys = klass.supported_validations
+        keys |= [ "searchable" ] if FieldDefinition::Searchable::SEARCHABLE_TYPES.include?(klass.name)
+        keys
+      end
+
+      def flag_unrestricted_specific_scope(type_handle, metadata, context)
+        return unless type_handle == "file" && metadata["file_scope"] == "specific"
+
+        presets = FieldDefinitions::File::FILE_TYPE_PRESETS.keys
+        return if Array(metadata["selected_presets"]).map(&:to_s).intersect?(presets)
+
+        flag %(#{context}: metadata.selected_presets must list at least one valid preset (#{presets.join(', ')}) when file_scope is "specific")
+      end
+
+      def validate_known_block_definitions(handles, context)
+        (handles.map(&:to_s) - known_block_definition_handles).each do |handle|
+          flag %(#{context}: unknown block definition "#{handle}")
+        end
+      end
+
+      def validate_known_content_types(handles, context)
+        (handles.map(&:to_s) - known_content_type_handles).each do |handle|
+          flag %(#{context}: unknown content type "#{handle}")
+        end
+      end
+
+      def known_block_definition_handles
+        @known_block_definition_handles ||= known_handles(:block_definitions, BlockDefinition)
+      end
+
+      def known_content_type_handles
+        @known_content_type_handles ||= known_handles(:content_types, ContentType)
+      end
+
+      def known_handles(section, schemable_class)
+        declared = declared_handles(section)
+        prune? ? declared : declared | schemable_class.pluck(:handle)
+      end
+
+      def prune?
+        @prune
+      end
+
+      def declared_handles(section)
+        (schema[section] || []).filter_map { |attrs| attrs[:handle].to_s if attrs.is_a?(Hash) }
+      end
+  end
+end

data/app/models/iron/schema.rb

@@ -0,0 +1,282 @@
+module Iron
+  class Schema
+    DEFAULT_PATH = "db/cms/schema.json"
+
+    class_attribute :editable_in_environment, instance_accessor: false, default: ->(env) { env.development? || env.test? }
+
+    class FileMissing < StandardError; end
+
+    class InvalidSchema < StandardError
+      attr_reader :problems
+
+      def initialize(problems)
+        @problems = Array(problems)
+        super(@problems.join("\n"))
+      end
+    end
+
+    class << self
+      include Lexorank::Utils
+
+      def editable?
+        editable_in_environment.call(Rails.env)
+      end
+
+      def locked?
+        !editable?
+      end
+
+      def path_for(path = nil)
+        Pathname.new(path || Rails.root.join(DEFAULT_PATH))
+      end
+
+      def dump(path = nil)
+        path_for(path).tap do |file|
+          FileUtils.mkdir_p(file.dirname)
+          file.write("#{to_json}\n")
+        end
+      end
+
+      def to_json
+        JSON.pretty_generate(export_hash)
+      end
+
+      def export_hash
+        {
+          version: "1.0",
+          default_locale: Current.account&.default_locale&.code,
+          locales: export_locales,
+          block_definitions: export_block_definitions,
+          content_types: export_content_types
+        }
+      end
+
+      def diff(path = nil)
+        schema = parse(path)
+        validate!(schema)
+
+        Diff.new(schema)
+      end
+
+      def apply(path = nil, prune: false)
+        schema = parse(path)
+        validate!(schema, prune:)
+
+        Diff.new(schema).tap do |diff|
+          suppress_auto_dump do
+            ActiveRecord::Base.transaction do
+              import(schema)
+              prune!(diff) if prune
+            end
+          end
+        end
+      end
+
+      def import(schema)
+        suppress_auto_dump do
+          ActiveRecord::Base.transaction do
+            import_locales(schema[:locales] || [])
+            ensure_account!(schema)
+            import_block_definitions(schema[:block_definitions] || [])
+            populate_block_field_definitions(schema[:block_definitions] || [])
+            import_content_types(schema[:content_types] || [])
+            resolve_supported_definitions(schema)
+            resolve_content_type_references(schema[:content_types] || [])
+            restore_default_locale(schema[:default_locale])
+          end
+        end
+      end
+
+      def note_change
+        ActiveSupport::IsolatedExecutionState[:iron_schema_change_noted] = true
+      end
+
+      def forget_change
+        ActiveSupport::IsolatedExecutionState[:iron_schema_change_noted] = nil
+      end
+
+      def auto_dump
+        return unless change_noted?
+        forget_change
+
+        return unless editable?
+        return if auto_dump_suppressed?
+        return unless path_for.exist?
+
+        dump
+      end
+
+      def suppress_auto_dump
+        previous = ActiveSupport::IsolatedExecutionState[:iron_schema_auto_dump_suppressed]
+        ActiveSupport::IsolatedExecutionState[:iron_schema_auto_dump_suppressed] = true
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState[:iron_schema_auto_dump_suppressed] = previous
+      end
+
+      private
+
+        def parse(path)
+          file = path_for(path)
+          raise FileMissing, "No schema file at #{file} — run bin/rails iron:schema:dump to create one from the current database" unless file.exist?
+
+          schema = JSON.parse(file.read, symbolize_names: true)
+          raise InvalidSchema, [ "schema must be a JSON object" ] unless schema.is_a?(Hash)
+
+          schema
+        rescue JSON::ParserError => error
+          raise InvalidSchema, [ "#{file}: #{error.message}" ]
+        end
+
+        def validate!(schema, prune: false)
+          problems = Validation.new(schema, prune:).problems
+          raise InvalidSchema, problems if problems.any?
+        end
+
+        def auto_dump_suppressed?
+          !!ActiveSupport::IsolatedExecutionState[:iron_schema_auto_dump_suppressed]
+        end
+
+        def change_noted?
+          !!ActiveSupport::IsolatedExecutionState[:iron_schema_change_noted]
+        end
+
+        def export_locales
+          Locale.order(:code).map { |locale| { code: locale.code, name: locale.name } }
+        end
+
+        def export_block_definitions
+          BlockDefinition.order(:handle).map(&:export_attributes)
+        end
+
+        def export_content_types
+          ContentType.order(:handle).map(&:export_attributes)
+        end
+
+        def import_locales(locales)
+          locales.each do |attrs|
+            locale = Locale.find_or_create_by!(code: attrs[:code]) do |new_locale|
+              new_locale.name = attrs[:name]
+            end
+            locale.update!(name: attrs[:name]) if attrs[:name].present? && locale.name != attrs[:name]
+          end
+        end
+
+        def ensure_account!(schema)
+          Account.first || Account.create!(name: "Iron", default_locale: bootstrap_locale(schema))
+        end
+
+        def bootstrap_locale(schema)
+          Locale.find_by(code: schema[:default_locale]) ||
+            Locale.first ||
+            Locale.find_or_create_by!(code: "en") { |locale| locale.name = "English" }
+        end
+
+        def import_block_definitions(definitions)
+          definitions.each { |attrs| BlockDefinition.import_from_attributes(attrs) }
+        end
+
+        def populate_block_field_definitions(definitions)
+          definitions.each do |attrs|
+            BlockDefinition.populate_field_definitions(attrs)
+            align_field_order(BlockDefinition.find_by!(handle: attrs[:handle]), attrs[:field_definitions] || [])
+          end
+        end
+
+        def import_content_types(definitions)
+          definitions.each do |attrs|
+            content_type = ContentType.import_from_attributes(attrs)
+            align_field_order(content_type, attrs[:field_definitions] || [])
+          end
+        end
+
+        # Schema files carry no ranks: array order is the field order. Ranks are
+        # only rewritten when the relative order in the database disagrees, so a
+        # no-op apply never churns updated_at.
+        def align_field_order(schemable, field_attrs_list)
+          file_handles = field_attrs_list.map { |attrs| attrs[:handle].to_s }
+          listed = schemable.field_definitions.reload.select { |definition| file_handles.include?(definition.handle) }
+          return if listed.map(&:handle) == file_handles
+
+          interval = optimal_rank_numeric_interval_for(file_handles.size)
+          by_handle = listed.index_by(&:handle)
+          file_handles.each.with_index(1) do |handle, index|
+            by_handle[handle]&.update!(rank: to_rank(interval * index))
+          end
+        end
+
+        # Fields can support content types declared later in the file, so the
+        # supported lists are wired again once every definition exists.
+        def resolve_supported_definitions(schema)
+          repopulate_supported_definitions(BlockDefinition, schema[:block_definitions] || [])
+          repopulate_supported_definitions(ContentType, schema[:content_types] || [])
+        end
+
+        def repopulate_supported_definitions(schemable_class, definitions)
+          definitions.each do |attrs|
+            schemable = schemable_class.find_by(handle: attrs[:handle])
+            next unless schemable
+
+            (attrs[:field_definitions] || []).each do |field_attrs|
+              field = schemable.field_definitions.find_by(handle: field_attrs[:handle])
+              FieldDefinition.assign_supported_definitions(field, field_attrs) if field
+            end
+          end
+        end
+
+        # Omitted handles clear the reference: the file is authoritative.
+        def resolve_content_type_references(definitions)
+          definitions.each do |attrs|
+            content_type = ContentType.find_by(handle: attrs[:handle])
+            next unless content_type
+
+            content_type.update!(
+              title_field_definition: content_type.field_definitions.find_by(handle: attrs[:title_field_handle]),
+              web_page_title_field_definition: content_type.field_definitions.find_by(handle: attrs[:web_page_title_field_handle])
+            )
+          end
+        end
+
+        def restore_default_locale(locale_code)
+          return unless locale_code
+
+          locale = Locale.find_by(code: locale_code)
+          Current.account.update!(default_locale: locale) if locale
+        end
+
+        def prune!(diff)
+          removals = diff.removals
+
+          removals[:content_types].each { |handle| ContentType.find_by(handle:)&.destroy! }
+          removals[:block_definitions].each { |handle| BlockDefinition.find_by(handle:)&.destroy! }
+
+          prune_field_definitions(ContentType, removals[:content_type_fields])
+          prune_field_definitions(BlockDefinition, removals[:block_definition_fields])
+
+          prune_locales(removals[:locales], diff)
+        end
+
+        def prune_field_definitions(schemable_class, field_handles_by_schemable)
+          field_handles_by_schemable.each do |schemable_handle, field_handles|
+            schemable_class.find_by(handle: schemable_handle)&.field_definitions&.where(handle: field_handles)&.destroy_all
+          end
+        end
+
+        def prune_locales(codes, diff)
+          Locale.where(code: codes).find_each do |locale|
+            if locale.default?
+              diff.add_note %(locale "#{locale.code}" is the account default locale — left in place)
+            elsif locale_has_content?(locale)
+              diff.add_note %(locale "#{locale.code}" still has content — left in place (delete its content first))
+            else
+              locale.destroy!
+            end
+          end
+        end
+
+        def locale_has_content?(locale)
+          Field.exists?(locale:) || SearchRecord.exists?(locale:)
+        end
+    end
+  end
+end

data/app/models/iron/seed.rb

@@ -14,9 +14,11 @@ module Iron
       return unless path.exist?
       return if already_seeded?
 
-      user, account = bootstrap
-      Current.set(user: user, account: account) do
-        Importer.new(path).import
+      Schema.suppress_auto_dump do
+        user, account = bootstrap
+        Current.set(user: user, account: account) do
+          Importer.new(path).import
+        end
       end
     end