mxrb 0.1.0

data/lib/mxrb/model/design_materializer.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+module Mxrb
+  module Model
+    # Materializes the typed design-system contract into MXRB-owned theme files.
+    class DesignMaterializer
+      IMPORT = '@import "mxrb-design-system";'
+
+      def initialize(root, definition)
+        @root = File.expand_path(root)
+        @definition = definition
+      end
+
+      def materialize!
+        tokens = valued_tokens(@definition.fetch(:tokens, []))
+        themes = resolved_themes
+        return self if tokens.empty? && themes.empty?
+
+        write(File.join('theme', 'web', '_mxrb-design-system.scss'), stylesheet(tokens, themes))
+        ensure_import
+        write(
+          File.join('themesource', 'mxrb', 'web', 'design-properties.json'),
+          JSON.pretty_generate(design_properties(tokens)) << "\n"
+        )
+        self
+      end
+
+      private
+
+      def valued_tokens(tokens) = Array(tokens).reject { _1[:value].nil? }
+
+      def resolved_themes
+        themes = Array(@definition[:themes]).to_h { [_1.fetch(:name).to_s, _1] }
+        themes.keys.sort.map { [_1, resolve_theme(_1, themes, [])] }
+      end
+
+      def resolve_theme(name, themes, trail)
+        return [] unless themes.key?(name)
+        raise SerializationError, "design-system theme inheritance cycle: #{(trail + [name]).join(' -> ')}" \
+          if trail.include?(name)
+
+        theme = themes.fetch(name)
+        inherited = theme[:inherits] ? resolve_theme(theme[:inherits].to_s, themes, trail + [name]) : []
+        merge_tokens(inherited, valued_tokens(theme.fetch(:tokens, [])))
+      end
+
+      def merge_tokens(inherited, own) = (inherited + own).reverse.uniq { token_property(_1) }.reverse
+
+      def stylesheet(tokens, themes)
+        sections = []
+        sections << css_block(':root', tokens) unless tokens.empty?
+        themes.reject { _2.empty? }.each do |name, theme_tokens|
+          slug = slug(name)
+          sections << css_block(
+            %(:root[data-mxrb-theme="#{slug}"], .mxrb-theme-#{slug}),
+            theme_tokens
+          )
+        end
+        "/* Generated by MXRB from the Ruby design_system contract. */\n#{sections.join("\n\n")}\n"
+      end
+
+      def css_block(selector, tokens)
+        declarations = tokens.map do |token|
+          "  #{token_property(token)}: #{safe_value(token.fetch(:value))};"
+        end
+        "#{selector} {\n#{declarations.join("\n")}\n}"
+      end
+
+      def token_property(token)
+        name = token.fetch(:name).to_s
+        return name if name.match?(/\A--[a-zA-Z0-9_-]+\z/)
+        return "--#{slug(name.delete_prefix('$'))}" if name.start_with?('$')
+
+        "--#{slug(token.fetch(:kind))}-#{slug(name)}"
+      end
+
+      def safe_value(value)
+        text = value.to_s.strip
+        raise SerializationError, "unsafe design-system token value: #{value.inspect}" \
+          if text.empty? || text.match?(/[\n\r;{}]/)
+
+        text
+      end
+
+      def slug(value)
+        result = value.to_s.gsub(/([a-z\d])([A-Z])/, '\1-\2')
+                      .downcase.gsub(/[^a-z0-9_-]+/, '-').gsub(/\A-+|-+\z/, '')
+        raise SerializationError, "invalid design-system name: #{value.inspect}" if result.empty?
+
+        result
+      end
+
+      def design_properties(tokens)
+        colors = tokens.select { _1.fetch(:kind).to_sym == :color }.map do |token|
+          {
+            'category' => 'MXRB design system',
+            'name' => human_name(token.fetch(:name)),
+            'type' => 'ColorPicker',
+            'property' => token_property(token)
+          }
+        end
+        { 'Widget' => colors }
+      end
+
+      def human_name(name) = slug(name.to_s.delete_prefix('$').delete_prefix('--'))
+        .split('-').map(&:capitalize).join(' ')
+
+      def ensure_import
+        path = File.join(@root, 'theme', 'web', 'main.scss')
+        current = File.file?(path) ? File.binread(path) : ''
+        return if current.lines.map(&:strip).include?(IMPORT)
+
+        separator = current.empty? || current.end_with?("\n") ? '' : "\n"
+        write(File.join('theme', 'web', 'main.scss'), "#{current}#{separator}#{IMPORT}\n")
+      end
+
+      def write(relative, contents)
+        target = File.join(@root, relative)
+        temporary = "#{target}.mxrb-#{Process.pid}"
+        begin
+          FileUtils.mkdir_p(File.dirname(target))
+          File.binwrite(temporary, contents)
+          FileUtils.mv(temporary, target)
+        ensure
+          FileUtils.rm_f(temporary)
+        end
+      end
+    end
+  end
+end

data/lib/mxrb/model/design_migration.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+
+module Mxrb
+  module Model
+    DesignMigrationChange = Data.define(:path, :before, :after, :occurrences)
+
+    # Immutable preview of literal-to-token stylesheet replacements.
+    class DesignMigrationPlan
+      attr_reader :changes
+
+      def self.build(root, replacements)
+        pairs = replacements.to_h.transform_keys(&:to_s).transform_values(&:to_s)
+        changes = stylesheet_paths(root).filter_map { migration_change(root, _1, pairs) }
+        new(root, changes)
+      end
+
+      def self.stylesheet_paths(root)
+        paths = DesignSystem::ASSET_DIRECTORIES.flat_map do |directory|
+          Dir.glob(File.join(root, directory, '**', '*.{css,scss}'))
+        end
+        paths.select { File.file?(_1) && !File.symlink?(_1) }.sort
+      end
+
+      def self.migration_change(root, path, pairs)
+        before = File.binread(path)
+        after = pairs.reduce(before) { |text, (literal, token)| text.gsub(literal, token) }
+        return if after == before
+
+        relative = Pathname.new(path).relative_path_from(Pathname.new(root)).to_s
+        occurrences = pairs.sum { |literal, _| before.scan(literal).size }
+        DesignMigrationChange.new(relative, before, after, occurrences)
+      end
+      private_class_method :stylesheet_paths, :migration_change
+
+      def initialize(root, changes)
+        @root = File.expand_path(root)
+        @changes = changes.freeze
+        @digests = changes.to_h { [_1.path, Digest::SHA256.hexdigest(_1.before)] }.freeze
+        @after_digests = changes.to_h { [_1.path, Digest::SHA256.hexdigest(_1.after)] }.freeze
+        @applied = false
+      end
+
+      def empty? = @changes.empty?
+      def applied? = @applied
+
+      def apply!
+        raise ArgumentError, 'design migration plan was already applied' if @applied
+
+        verify_changes!(@digests, 'changed after preview')
+        replace_all!(fallback: :before, &:after)
+        @applied = true
+        self
+      end
+
+      # Restores the previewed contents when a surrounding batch fails.
+      def rollback!
+        return self unless @applied
+
+        verify_changes!(@after_digests, 'changed after migration')
+        replace_all!(fallback: :after, &:before)
+        @applied = false
+        self
+      end
+
+      private
+
+      def verify_changes!(digests, reason)
+        @changes.each do |change|
+          target = File.join(@root, change.path)
+          unless File.file?(target) && Digest::SHA256.file(target).hexdigest == digests.fetch(change.path)
+            raise SerializationError, "design asset #{reason}: #{change.path}"
+          end
+        end
+      end
+
+      def replace_all!(fallback:)
+        staged = {}
+        staged = stage_changes { yield(_1) }
+        commit_staged!(staged, fallback)
+      ensure
+        staged.each_value { FileUtils.rm_f(_1) }
+      end
+
+      def stage_changes
+        @changes.to_h do |change|
+          temporary = temporary_path(change.path)
+          File.binwrite(temporary, yield(change))
+          [change.path, temporary]
+        end
+      end
+
+      def commit_staged!(staged, fallback)
+        committed = []
+        @changes.each do |change|
+          FileUtils.mv(staged.fetch(change.path), File.join(@root, change.path))
+          committed << change
+        end
+      rescue StandardError
+        restore_committed!(committed, fallback)
+        raise
+      end
+
+      def restore_committed!(committed, fallback)
+        committed.reverse_each do |change|
+          target = File.join(@root, change.path)
+          temporary = "#{target}.mxrb-rollback-#{Process.pid}-#{staged_suffix(change.path)}"
+          File.binwrite(temporary, change.public_send(fallback))
+          FileUtils.mv(temporary, target)
+        ensure
+          FileUtils.rm_f(temporary)
+        end
+      end
+
+      def staged_suffix(path)
+        Digest::SHA256.hexdigest(path)[0, 12]
+      end
+
+      def temporary_path(path)
+        "#{File.join(@root, path)}.mxrb-#{Process.pid}-#{staged_suffix(path)}"
+      end
+    end
+  end
+end

data/lib/mxrb/model/design_system.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Mxrb
+  module Model
+    DesignToken = Data.define(:name, :value, :kind, :theme, :path, :line)
+
+    # Read-only inventory and quality metrics for Mendix theme assets.
+    class DesignSystem
+      ASSET_DIRECTORIES = %w[
+        theme theme-cache themesource resources widgets javasource javascriptsource
+        userlib vendorlib
+      ].freeze
+      CSS_TOKEN = /(?<name>--[A-Za-z0-9_-]+)\s*:\s*(?<value>[^;{}]+);/
+      SCSS_TOKEN = /(?<name>\$[A-Za-z0-9_-]+)\s*:\s*(?<value>[^;{}]+);/
+
+      attr_reader :root
+
+      def initialize(root)
+        @root = File.expand_path(root)
+      end
+
+      def tokens
+        @tokens ||= stylesheet_paths.flat_map { scan_stylesheet(_1) }.freeze
+      end
+
+      def themes
+        tokens.map(&:theme).compact.uniq.sort.freeze
+      end
+
+      def catalogs
+        Dir.glob(File.join(@root, 'themesource', '**', 'design-properties.json')).sort.to_h do |path|
+          [relative(path), JSON.parse(File.read(path))]
+        rescue JSON::ParserError
+          [relative(path), nil]
+        end.freeze
+      end
+
+      def unresolved_references
+        names = tokens.map(&:name).to_h { [_1, true] }
+        tokens.flat_map do |token|
+          token.value.scan(/var\((--[A-Za-z0-9_-]+)/).flatten.reject { names.key?(_1) }
+               .map do
+            {
+              token:, reference: _1
+            }.freeze
+          end
+        end.freeze
+      end
+
+      def literal_colors
+        tokens.select { _1.value.match?(/#[0-9a-f]{3,8}\b/i) }.freeze
+      end
+
+      def contrast_ratio(foreground, background)
+        light, dark = [relative_luminance(foreground), relative_luminance(background)].sort.reverse
+        ((light + 0.05) / (dark + 0.05)).round(2)
+      end
+
+      def plan_literal_migration(replacements)
+        DesignMigrationPlan.build(@root, replacements)
+      end
+
+      private
+
+      def stylesheet_paths
+        paths = ASSET_DIRECTORIES.flat_map do |directory|
+          Dir.glob(File.join(@root, directory, '**', '*.{css,scss}'))
+        end
+        paths.select { File.file?(_1) }.sort
+      end
+
+      def scan_stylesheet(path)
+        theme = File.basename(path)[/\A_theme-([^.]+)/, 1]
+        File.readlines(path).each_with_index.flat_map do |line, index|
+          next [] if line.lstrip.start_with?('//')
+
+          line.scan(CSS_TOKEN).map { token(_1, :css_custom_property, theme, path, index) } +
+            line.scan(SCSS_TOKEN).map { token(_1, :scss_variable, theme, path, index) }
+        end
+      end
+
+      def token(match, kind, theme, path, index)
+        DesignToken.new(match[0], match[1].strip, kind, theme, relative(path), index + 1)
+      end
+
+      def relative(path) = Pathname.new(path).relative_path_from(Pathname.new(@root)).to_s
+
+      def relative_luminance(color)
+        hex = normalized_hex(color)
+        channels = hex.scan(/../).map { linear_channel(_1.to_i(16) / 255.0) }
+        (0.2126 * channels[0]) + (0.7152 * channels[1]) + (0.0722 * channels[2])
+      end
+
+      def normalized_hex(color)
+        hex = color.to_s.delete_prefix('#')
+        hex = hex.chars.flat_map { [_1, _1] }.join if hex.length == 3
+        raise ArgumentError, 'expected a three- or six-digit hex color' unless hex.match?(/\A[0-9a-f]{6}\z/i)
+
+        hex
+      end
+
+      def linear_channel(channel)
+        return channel / 12.92 if channel <= 0.04045
+
+        ((channel + 0.055) / 1.055)**2.4
+      end
+    end
+  end
+end

data/lib/mxrb/model/domain_model.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "unit"
+require_relative "entity"
+require_relative "association"
+
+module Mxrb
+  module Model
+    # $Type: DomainModels$DomainModel
+    # ContainmentName: "DomainModel"
+    # Unlike entities/attributes, DomainModel IS its own Unit row.
+    # Entities and Attributes are embedded inside the DomainModel BSON (not separate Unit rows).
+    class DomainModel < Unit
+      attr_reader :documentation, :annotations
+
+      def decode(doc)
+        @documentation = doc["documentation"] || doc["Documentation"] || ""
+        @annotations   = parse_array(doc["annotations"] || doc["Annotations"])
+
+        entity_docs = parse_array(doc["entities"] || doc["Entities"])
+        @entities   = entity_docs.map { Entity.from_bson(_1, @id, @mpr) }
+
+        assoc_docs   = parse_array(doc["associations"] || doc["Associations"])
+        @associations = assoc_docs.map { Association.from_bson(_1, @id, @mpr) }
+        cross_docs = parse_array(doc["crossAssociations"] || doc["CrossAssociations"])
+        @cross_associations = cross_docs.map { Association.from_bson(_1, @id, @mpr) }
+      end
+
+      def entities     = @entities     || []
+      def local_associations = @associations || []
+      def cross_associations = @cross_associations || []
+      def associations = local_associations + cross_associations
+
+      def to_bson
+        {
+          "$ID"           => @id,
+          "$Type"         => "DomainModels$DomainModel",
+          "entities"      => IO::BsonCodec.build_array(@entities.map(&:to_bson)),
+          "associations"  => IO::BsonCodec.build_array(local_associations.map(&:to_bson)),
+          "crossAssociations" => IO::BsonCodec.build_array(cross_associations.map(&:to_bson)),
+          "annotations"   => IO::BsonCodec.build_array([]),
+          "documentation" => @documentation || "",
+        }
+      end
+
+      def inspect
+        "#<Mxrb::DomainModel entities=#{entities.size} associations=#{associations.size}>"
+      end
+    end
+  end
+end

data/lib/mxrb/model/entity.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "attribute"
+
+module Mxrb
+  module Model
+    # Entities are embedded in the DomainModel BSON — NOT separate Unit rows.
+    # $Type: DomainModels$Entity (read) / DomainModels$EntityImpl (write)
+    class Entity # rubocop:disable Metrics/ClassLength
+      attr_accessor :id, :name, :qualified_name, :documentation,
+                    :persistable, :location, :data_storage_guid,
+                    :export_level, :generalization, :access_rules, :indexes,
+                    :system_members
+
+      # Build from a BSON hash (embedded in DomainModel's "entities" array).
+      def self.from_bson(doc, _domain_model_id, mpr)
+        e                    = new
+        e.id                 = IO::BsonCodec.extract_id(doc["$ID"] || doc["\$ID"])
+        e.name               = doc["name"]  || doc["Name"]
+        e.qualified_name     = doc["$QualifiedName"] || doc["\$QualifiedName"]
+        e.documentation      = doc["documentation"] || doc["Documentation"] || ""
+        e.data_storage_guid  = doc["dataStorageGuid"] || doc["DataStorageGuid"]
+        e.export_level       = doc["exportLevel"] || doc["ExportLevel"] || "Hidden"
+        e.location           = parse_location(doc["location"] || doc["Location"])
+
+        # Persistable lives inside generalization.NoGeneralization.persistable
+        gen = doc["generalization"] || doc["Generalization"] ||
+              doc["maybeGeneralization"] || doc["MaybeGeneralization"]
+        e.generalization = gen
+        persistable = if gen.is_a?(Hash)
+                        gen.fetch('persistable', gen.fetch('Persistable', true))
+                      else
+                        true
+                      end
+        e.persistable = persistable != false
+        e.system_members = parse_system_members(gen)
+
+        # Attributes (embedded array with marker)
+        attr_arr   = IO::BsonCodec.parse_array(doc["attributes"] || doc["Attributes"])[:items]
+        e.instance_variable_set(:@attributes, attr_arr.map { Attribute.from_bson(_1) })
+        rules = IO::BsonCodec.parse_array(doc['validationRules'] || doc['ValidationRules'])[:items]
+        apply_validation_rules(e.attributes, rules)
+        raw_indexes = IO::BsonCodec.parse_array(doc['indexes'] || doc['Indexes'])[:items]
+        e.indexes = normalize_indexes(raw_indexes, e.attributes, e.qualified_name)
+
+        # Access rules (embedded array with marker 3)
+        rule_arr = IO::BsonCodec.parse_array(doc["accessRules"] || doc["AccessRules"])[:items]
+        e.access_rules = rule_arr.map { parse_access_rule(_1) }
+
+        e
+      end
+
+      def attributes = @attributes || []
+
+      def generalization_target
+        return unless @generalization.is_a?(Hash)
+
+        @generalization['generalization'] || @generalization['Generalization']
+      end
+
+      def to_bson
+        {
+          "$ID"             => @id,
+          "$Type"           => "DomainModels$EntityImpl",
+          "$QualifiedName"  => @qualified_name,
+          "name"            => @name,
+          "documentation"   => @documentation || "",
+          "dataStorageGuid" => @data_storage_guid || SecureRandom.uuid,
+          "location"        => serialize_location(@location),
+          "generalization"  => serialize_generalization,
+          "attributes"      => IO::BsonCodec.build_array(@attributes.map(&:to_bson)),
+          "validationRules" => IO::BsonCodec.build_array([]),  # must come after attributes
+          "eventHandlers"   => IO::BsonCodec.build_array([]),
+          "indexes"         => IO::BsonCodec.build_array([]),
+          "accessRules"     => IO::BsonCodec.build_array(@access_rules.to_a),
+          "source"          => nil,
+          "exportLevel"     => @export_level || "Hidden",
+          "image"           => "",
+          "imageData"       => "",
+        }
+      end
+
+      def inspect
+        "#<Mxrb::Entity name=#{@name.inspect} attrs=#{attributes.size} persistable=#{@persistable}>"
+      end
+
+      private
+
+      def self.apply_validation_rules(attributes, rules)
+        by_name = attributes.to_h { [_1.name, _1] }
+        rules.each do |rule|
+          attribute = by_name[rule['Attribute'].to_s.split('.').last]
+          next unless attribute
+
+          kind = rule.dig('RuleInfo', '$Type').to_s
+          attribute.required = true if kind.end_with?('RequiredRuleInfo')
+          attribute.unique = true if kind.end_with?('UniqueRuleInfo')
+        end
+      end
+
+      def self.normalize_indexes(indexes, attributes, qualified_name)
+        names_by_id = attributes.to_h { [_1.id, _1.name] }
+        indexes.each do |index|
+          members = IO::BsonCodec.parse_array(index['Attributes'])[:items]
+          members.each do |member|
+            next if member['Attribute'] || member['attribute']
+
+            id = IO::BsonCodec.extract_id(member['AttributePointer'])
+            name = names_by_id[id]
+            member['Attribute'] = [qualified_name, name].compact.join('.') if name
+          end
+        end
+      end
+
+      def self.parse_system_members(generalization)
+        return {} unless generalization.is_a?(Hash)
+
+        {
+          owner: generalization['hasOwner'] == true || generalization['HasOwnerAttr'] == true,
+          created_date: generalization.values_at(
+            'hasCreatedDate', 'HasCreatedDateAttr'
+          ).include?(true),
+          changed_date: generalization.values_at(
+            'hasChangedDate', 'HasChangedDateAttr'
+          ).include?(true),
+          changed_by: generalization.values_at(
+            'hasChangedBy', 'HasChangedByAttr'
+          ).include?(true)
+        }
+      end
+
+      def self.parse_access_rule(doc)
+        roles = IO::BsonCodec.parse_array(doc["ModuleRoles"] || doc["AllowedModuleRoles"])[:items]
+        default_rights = doc["DefaultMemberAccessRights"] || "None"
+        member_items = IO::BsonCodec.parse_array(doc["MemberAccesses"])[:items]
+        members = member_items.map do |m|
+          association_ref = m["Association"].to_s
+          attr_ref = association_ref.empty? ? m["Attribute"] : association_ref
+          kind = association_ref.empty? ? :attribute : :association
+          { name: attr_ref.to_s.split(%r{[/.]}).last, reference: attr_ref.to_s,
+            rights: m["AccessRights"] || "None", kind: kind }
+        end
+        {
+          roles: roles,
+          create: doc["AllowCreate"] == true,
+          delete: doc["AllowDelete"] == true,
+          default_rights: default_rights,
+          members: members,
+          xpath: doc["XPathConstraint"] || ""
+        }
+      end
+
+      def self.parse_location(loc)
+        if loc.is_a?(String)
+          x, y = loc.split(';', 2).map(&:to_i)
+          return { x: x, y: y }
+        end
+        return { x: 0, y: 0 } unless loc.is_a?(Hash)
+        { x: loc["x"] || loc[:x] || 0, y: loc["y"] || loc[:y] || 0 }
+      end
+
+      def serialize_location(loc)
+        return { "x" => 0, "y" => 0 } unless loc
+        { "x" => loc[:x] || 0, "y" => loc[:y] || 0 }
+      end
+
+      def serialize_generalization
+        @generalization || {
+          "$ID"             => SecureRandom.uuid,
+          "$Type"           => "DomainModels$NoGeneralization",
+          "persistable"     => @persistable != false,
+          "hasChangedDate"  => false,
+          "hasCreatedDate"  => false,
+          "hasOwner"        => false,
+          "hasChangedBy"    => false,
+        }
+      end
+    end
+  end
+end

data/lib/mxrb/model/menu.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "unit"
+
+module Mxrb
+  module Model
+    class Menu < Unit
+      attr_reader :name, :items, :raw_document
+
+      def decode(doc)
+        @raw_document = doc
+        @name = doc["Name"]
+        collection = doc["ItemCollection"] || {}
+        @items = parse_array(collection["Items"]).map { menu_item(_1) }
+      end
+
+      private
+
+      def menu_item(doc)
+        {
+          name: doc["Name"],
+          caption: extract_text(doc["Caption"]),
+          page: doc.dig("Action", "FormSettings", "Form"),
+          items: parse_array(doc["Items"]).map { menu_item(_1) }
+        }.compact
+      end
+
+      def extract_text(obj)
+        return "" unless obj.is_a?(Hash)
+
+        translation = parse_array(obj["Items"] || obj["Translations"]).find { _1.is_a?(Hash) }
+        return "" unless translation
+
+        translation["Text"] || translation["Translation"] || ""
+      end
+    end
+  end
+end