mxrb 0.1.0

data/lib/mxrb/initializer.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tmpdir'
+
+module Mxrb
+  # Creates the minimum editable Ruby project accepted by `mxrb generate`.
+  # rubocop:disable Metrics/ClassLength
+  class Initializer
+    Result = Data.define(:root, :files)
+    NAME = /\A[A-Za-z][A-Za-z0-9_-]*\z/
+    COMPOUND_SUFFIXES = %w[service clinic portal demo api app kit].freeze
+
+    def initialize(name, subject: :project, mxrb_path: nil)
+      @dir_name = name.to_s
+      raise ArgumentError, "#{subject} name must be snake_case or PascalCase" unless NAME.match?(@dir_name)
+
+      @module_name = to_pascal_case(@dir_name)
+      @mpr_name = "#{@module_name}.mpr"
+      @mxrb_path = File.expand_path(mxrb_path) if mxrb_path
+      raise ArgumentError, "mxrb path does not exist: #{@mxrb_path}" if @mxrb_path && !File.directory?(@mxrb_path)
+    end
+
+    def scaffold(into: Dir.pwd)
+      parent = File.expand_path(into)
+      root = File.join(parent, @dir_name)
+      abort "#{root}: directory already exists" if File.exist?(root)
+
+      FileUtils.mkdir_p(parent)
+      staging = Dir.mktmpdir(".#{@dir_name}.mxrb-init-", parent)
+      write_scaffold(staging)
+      FileUtils.mv(staging, root)
+      Result.new(root, relative_files.map { File.join(root, _1) }.freeze)
+    ensure
+      FileUtils.rm_rf(staging) if staging && File.exist?(staging)
+    end
+
+    private
+
+    def write_scaffold(root)
+      write(root, 'Gemfile', gemfile)
+      write(root, '.gitignore', gitignore)
+      write(root, '.env.example', env_example)
+      write(root, 'project.rb', project_rb)
+      write(File.join(root, 'app', 'navigation', 'responsive'), '.keep', '')
+      write_design_scaffold(root)
+      module_root = File.join(root, 'modules', @module_name)
+      write_module_scaffold(module_root)
+    end
+
+    def write_design_scaffold(root)
+      design_files.each do |parts, template|
+        write(File.join(root, *parts[0...-1]), parts.last, Scaffold::Templates.render(template))
+      end
+    end
+
+    def design_files
+      {
+        %w[app design_system design_system.rb] => :design_system,
+        %w[theme web custom-variables.scss] => :theme_custom_variables,
+        %w[theme web main.scss] => :theme_main,
+        %w[theme web exclusion-variables.scss] => :theme_exclusion_variables,
+        %w[theme web settings.json] => :theme_settings,
+        %w[theme-cache web theme.compiled.css] => :theme_compiled
+      }
+    end
+
+    def write_module_scaffold(module_root)
+      write(module_root, 'module.rb', module_rb)
+      write(File.join(module_root, 'domain'), 'model.rb', model_rb)
+      write(File.join(module_root, 'application'), 'application.rb', application_rb)
+      write(File.join(module_root, 'domain', 'entities'), '.keep', '')
+      write(File.join(module_root, 'presentation'), 'presentation.rb', presentation_rb)
+      write(File.join(module_root, 'presentation', 'pages'), 'home.rb', home_rb)
+    end
+
+    def relative_files
+      module_prefix = File.join('modules', @module_name)
+      ['Gemfile', '.gitignore', '.env.example', 'project.rb',
+       *relative_module_files.map { File.join(module_prefix, _1) },
+       File.join('app', 'navigation', 'responsive', '.keep'),
+       *design_files.keys.map { File.join(*_1) }]
+    end
+
+    def relative_module_files
+      [
+        'module.rb', File.join('domain', 'model.rb'),
+        File.join('application', 'application.rb'), File.join('domain', 'entities', '.keep'),
+        File.join('presentation', 'presentation.rb'), File.join('presentation', 'pages', 'home.rb')
+      ]
+    end
+
+    def to_pascal_case(value)
+      parts = value.split(/[_-]+/)
+      return parts.map { capitalize(_1) }.join if parts.length > 1
+      return capitalize(value) unless value == value.downcase
+
+      stem = value.sub(/\d+\z/, '')
+      digits = value.delete_prefix(stem)
+      compound_parts(stem).map { capitalize(_1) }.join + digits
+    end
+
+    def compound_parts(value)
+      suffix = COMPOUND_SUFFIXES.find { value.length > _1.length && value.end_with?(_1) }
+      return [value] unless suffix
+
+      [*compound_parts(value.delete_suffix(suffix)), suffix]
+    end
+
+    def capitalize(value) = value[0].upcase + value[1..]
+
+    def write(directory, name, content)
+      FileUtils.mkdir_p(directory)
+      File.binwrite(File.join(directory, name), content)
+    end
+
+    def gemfile
+      <<~RUBY
+        # frozen_string_literal: true
+
+        source "https://rubygems.org"
+
+        #{gem_declaration}
+        gem "dotenv", "~> 3.0"
+      RUBY
+    end
+
+    def gitignore
+      <<~TEXT
+        # Local environment and secrets. Commit only .env.example with blank values.
+        .env
+        .env.*
+        !.env.example
+      TEXT
+    end
+
+    def env_example
+      <<~TEXT
+        # Copy to .env and keep real values local. Never commit secrets.
+        MXRB_MENDIX_PAT=
+      TEXT
+    end
+
+    def gem_declaration
+      return 'gem "mxrb"' unless @mxrb_path
+
+      %(gem "mxrb", path: #{@mxrb_path.inspect})
+    end
+
+    def project_rb
+      <<~RUBY
+        # frozen_string_literal: true
+
+        require "dotenv/load"
+        require "mxrb"
+
+        output = ENV.fetch("MXRB_OUTPUT_PATH", File.join(__dir__, "#{@mpr_name}"))
+
+        Mxrb.define(output) do
+          mendix_version "11.12.1"
+
+          navigation do
+            profile :Responsive,
+                    home_page: "#{@module_name}.Home",
+                    app_title: "#{@module_name}" do
+              evaluate_dir File.join(__dir__, "app", "navigation", "responsive")
+            end
+          end
+
+          evaluate File.join(__dir__, "app", "design_system", "design_system.rb")
+          evaluate File.join(__dir__, "modules", "#{@module_name}", "module.rb")
+        end
+      RUBY
+    end
+
+    def module_rb
+      <<~RUBY
+        # frozen_string_literal: true
+
+        self.module :#{@module_name} do
+          evaluate File.join(__dir__, "domain", "model.rb")
+          evaluate File.join(__dir__, "application", "application.rb")
+          evaluate File.join(__dir__, "presentation", "presentation.rb")
+        end
+      RUBY
+    end
+
+    def model_rb
+      <<~RUBY
+        # frozen_string_literal: true
+
+        evaluate_dir File.join(__dir__, "enumerations")
+        evaluate_dir File.join(__dir__, "entities")
+      RUBY
+    end
+
+    def application_rb
+      <<~RUBY
+        # frozen_string_literal: true
+
+        evaluate_dir File.join(__dir__, "use_cases")
+        evaluate_dir File.join(__dir__, "validations")
+        evaluate_dir File.join(__dir__, "queries")
+      RUBY
+    end
+
+    def presentation_rb
+      <<~RUBY
+        # frozen_string_literal: true
+
+        layout :ApplicationLayout, title: "#{@module_name}"
+
+        evaluate_dir File.join(__dir__, "pages")
+        evaluate_dir File.join(__dir__, "snippets")
+        evaluate_dir File.join(__dir__, "client_actions")
+      RUBY
+    end
+
+    def home_rb
+      <<~RUBY
+        # frozen_string_literal: true
+
+        page :Home do
+          title "#{@module_name}"
+          layout "#{@module_name}.ApplicationLayout"
+
+          container :pageHeader, class_name: "mxrb-page-header" do
+            text :pageTitle, caption: "#{@module_name}"
+            text :pageSubtitle,
+                 caption: "A Ruby-first Mendix application, ready to grow."
+          end
+
+          container :dashboard, class_name: "mxrb-dashboard-grid" do
+            container :domainCard, class_name: "mxrb-card" do
+              text :domainEyebrow, caption: "DOMAIN"
+              text :domainTitle, caption: "Model your business"
+              text :domainCopy, caption: "Add entities, enumerations and associations using the mxrb DSL."
+            end
+
+            container :logicCard, class_name: "mxrb-card" do
+              text :logicEyebrow, caption: "LOGIC"
+              text :logicTitle, caption: "Build application flows"
+              text :logicCopy, caption: "Keep use cases, validations and queries organized by convention."
+            end
+
+            container :experienceCard, class_name: "mxrb-card" do
+              text :experienceEyebrow, caption: "EXPERIENCE"
+              text :experienceTitle, caption: "Ship a polished UI"
+              text :experienceCopy, caption: "Create pages, snippets and client actions without manual wiring."
+            end
+          end
+        end
+      RUBY
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/mxrb/integrity/validator.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Mxrb
+  module Integrity
+    Result = Struct.new(:errors, :warnings, keyword_init: true) do
+      def valid? = errors.empty?
+    end
+
+    class Validator
+      def initialize(path)
+        @path = path
+      end
+
+      def validate
+        @errors = []
+        @warnings = []
+        @mpr = IO::MprFile.open(@path, readonly: true)
+        validate_tables
+        validate_units
+        validate_v2_files
+        Result.new(errors: @errors, warnings: @warnings)
+      rescue Error => e
+        Result.new(errors: [e.message], warnings: @warnings || [])
+      ensure
+        @mpr&.close
+      end
+
+      private
+
+      def validate_tables
+        require_table("Unit")
+        require_table("_MetaData")
+        require_unit_column("UnitID")
+        require_unit_column("ContainerID")
+        require_unit_column("ContainmentName")
+        require_unit_column("ContentsHash")
+      end
+
+      def validate_units
+        @units = @mpr.all_units
+        validate_root
+        validate_unit_ids
+        validate_contents
+      end
+
+      def validate_root
+        roots = @units.select { _1["UnitID"] == _1["ContainerID"] }
+        add_error("expected exactly one root unit, found #{roots.size}") unless roots.size == 1
+      end
+
+      def validate_unit_ids
+        ids = @units.map { _1["UnitID"] }
+        ids.each { add_error("blank UnitID") if _1.to_s.empty? }
+        duplicates = ids.tally.select { |_id, count| count > 1 }.keys
+        duplicates.each { add_error("duplicate UnitID #{_1}") }
+
+        id_set = ids.to_set
+        @units.each do |unit|
+          parent = unit["ContainerID"]
+          next if parent == unit["UnitID"]
+
+          add_error("unit #{unit['UnitID']} references missing container #{parent}") unless id_set.include?(parent)
+        end
+      end
+
+      def validate_contents
+        @units.each do |unit|
+          bytes = @mpr.content_bytes(unit)
+          if bytes.nil? || bytes.empty?
+            add_error("unit #{unit['UnitID']} has no content bytes")
+            next
+          end
+
+          validate_hash(unit, bytes)
+          doc = parse_unit(unit)
+          next unless doc
+
+          validate_doc_identity(unit, doc)
+        end
+      end
+
+      def validate_hash(unit, bytes)
+        expected = unit["ContentsHash"].to_s
+        actual = IO::BsonCodec.contents_hash(bytes)
+        add_error("unit #{unit['UnitID']} ContentsHash mismatch") unless expected == actual
+      end
+
+      def parse_unit(unit)
+        @mpr.parse_contents(unit)
+      rescue IO::MxunitCodec::UnsupportedFormat, SerializationError => e
+        add_error("unit #{unit['UnitID']} content parse failed: #{e.message}")
+        nil
+      end
+
+      def validate_doc_identity(unit, doc)
+        type = doc["$Type"] || doc["\$Type"]
+        add_error("unit #{unit['UnitID']} missing $Type") if type.to_s.empty?
+
+        doc_id = IO::BsonCodec.extract_id(doc["$ID"] || doc["\$ID"])
+        if doc_id.to_s.empty?
+          add_error("unit #{unit['UnitID']} missing $ID")
+        elsif doc_id != unit["UnitID"]
+          add_error("unit #{unit['UnitID']} content $ID mismatch #{doc_id}")
+        end
+      end
+
+      def validate_v2_files
+        return unless @mpr.format_version == :v2
+
+        expected = @units.filter_map { @mpr.content_path(_1) }.to_set
+        actual = @mpr.content_files.to_set
+        (expected - actual).each { add_error("missing mxunit file #{_1}") }
+        (actual - expected).each { add_warning("orphan mxunit file #{_1}") }
+      end
+
+      def require_table(name)
+        add_error("missing #{name} table") unless @mpr.tables.include?(name)
+      end
+
+      def require_unit_column(name)
+        columns = @mpr.table_info("Unit").map { _1["name"] || _1[:name] }
+        add_error("missing Unit.#{name} column") unless columns.include?(name)
+      end
+
+      def add_error(message)
+        @errors << message
+      end
+
+      def add_warning(message)
+        @warnings << message
+      end
+    end
+  end
+end

data/lib/mxrb/io/bson_codec.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "bson"
+require "digest"
+require "base64"
+
+module Mxrb
+  module IO
+    # BSON codec with Mendix-specific conventions:
+    #   - UUIDs stored as 16-byte blobs with partial little-endian byte-swap (MS GUID format)
+    #   - Arrays have a 4-byte int32 marker as first element (1=by-name, 2=part-secondary, 3=part-primary)
+    #   - $ID can appear as String, BSON Binary, or {Data:, Subtype:} map
+    #   - $Type uses storage names ("DomainModels$Entity") not SDK qualified names
+    module BsonCodec
+      # ── UUID / BLOB conversion ─────────────────────────────────────────────
+
+      # Convert a 16-byte MS-GUID blob to UUID string.
+      # MS-GUID layout: bytes 0-3 little-endian, 4-5 little-endian, 6-7 little-endian,
+      # bytes 8-15 big-endian.
+      def self.blob_to_uuid(blob)
+        return nil unless blob.is_a?(String) && blob.bytesize == 16
+
+        b = blob.bytes
+        p1 = b[0..3].reverse.map { "%02x" % _1 }.join
+        p2 = b[4..5].reverse.map { "%02x" % _1 }.join
+        p3 = b[6..7].reverse.map { "%02x" % _1 }.join
+        p4 = b[8..9].map  { "%02x" % _1 }.join
+        p5 = b[10..15].map { "%02x" % _1 }.join
+        "#{p1}-#{p2}-#{p3}-#{p4}-#{p5}"
+      end
+
+      # Convert a UUID string to a 16-byte MS-GUID blob.
+      def self.uuid_to_blob(uuid)
+        hex   = uuid.delete("-")
+        parts = hex.scan(/../).map { _1.to_i(16).chr(Encoding::BINARY) }
+        (parts[0..3].reverse + parts[4..5].reverse + parts[6..7].reverse + parts[8..15]).join
+      end
+
+      # ── $ID extraction ─────────────────────────────────────────────────────
+
+      # Extract the Mendix $ID value from any of its three representations:
+      #   1. String UUID:  "c67c5271-da7d-45f1-81df-ceb6946b8abe"
+      #   2. BSON Binary:  <16-byte blob>  → converted to UUID string
+      #   3. Map:          { "Data" => "base64...", "Subtype" => 3 } → decoded + converted
+      def self.extract_id(value)
+        case value
+        when String
+          value  # already a UUID string
+        when BSON::Binary
+          blob_to_uuid(value.data)
+        when Hash
+          data = value["Data"] || value[:Data]
+          return nil unless data
+          blob_to_uuid(Base64.strict_decode64(data.to_s))
+        end
+      end
+
+      # ── Array parsing ───────────────────────────────────────────────────────
+
+      # Mendix arrays have an int32 marker as first element.
+      # Returns { marker: Integer, items: Array }
+      # Marker values: 1=by-name refs, 2=part-secondary, 3=part-primary
+      def self.parse_array(raw)
+        return { marker: 3, items: [] } if raw.nil? || raw.empty?
+
+        marker = raw.first.is_a?(Integer) ? raw.first : 3
+        items  = raw.first.is_a?(Integer) ? raw[1..] : raw
+        { marker: marker, items: Array(items) }
+      end
+
+      # Build a Mendix-style array (prepend marker).
+      def self.build_array(items, marker: 3)
+        [marker] + Array(items)
+      end
+
+      # ── BSON parse / serialize ──────────────────────────────────────────────
+
+      # Parse raw BSON bytes → Ruby Hash (with string keys).
+      def self.parse(bytes)
+        return {} if bytes.nil? || bytes.empty?
+
+        buf = BSON::ByteBuffer.new(bytes.b)
+        BSON::Document.from_bson(buf).to_h
+      rescue => e
+        raise SerializationError, "BSON parse error: #{e.message}"
+      end
+
+      # Serialize a Ruby Hash → BSON bytes.
+      def self.serialize(doc)
+        bson_doc = BSON::Document.new(storage_value(doc))
+        buf = BSON::ByteBuffer.new
+        bson_doc.to_bson(buf)
+        buf.get_bytes(buf.length)
+      rescue => e
+        raise SerializationError, "BSON serialize error: #{e.message}"
+      end
+
+      UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+      BINARY_UUID_KEYS = %w[
+        $ID ChildPointer CloseButtonPointer DataStorageGuid DefaultButtonPointer
+        DefaultPagePointer DestinationPointer GUID OriginPointer ParentPointer
+        StableId TypeParameterPointer TypePointer
+      ].freeze
+
+      def self.storage_value(value, key = nil)
+        if BINARY_UUID_KEYS.include?(key) &&
+            value.is_a?(String) && value.match?(UUID_PATTERN)
+          return BSON::Binary.new(uuid_to_blob(value), :generic)
+        end
+
+        case value
+        when Hash
+          value.to_h { |child_key, child| [child_key, storage_value(child, child_key.to_s)] }
+        when Array
+          value.map { storage_value(_1) }
+        else
+          value
+        end
+      end
+      private_class_method :storage_value
+
+      # ── ContentHash ────────────────────────────────────────────────────────
+
+      # Compute the Mendix ContentsHash: Base64(SHA256(bson_bytes)).
+      def self.contents_hash(bson_bytes)
+        Base64.strict_encode64(Digest::SHA256.digest(bson_bytes.b))
+      end
+
+      # ── Storage name helpers ───────────────────────────────────────────────
+
+      # Map ContainmentName → expected $Type prefix for quick type detection.
+      CONTAINMENT_TO_TYPE = {
+        "Modules"             => "Projects$Module",
+        "DomainModel"         => "DomainModels$DomainModel",
+        "Documents"           => nil,  # could be Page, Microflow, etc — read $Type
+        "Folders"             => "Projects$Folder",
+        "ModuleSecurity"      => "Security$ModuleSecurity",
+        "Settings"            => "Settings$ProjectSettings",
+        "Security"            => "Security$ProjectSecurity",
+        "NavigationDocuments" => "Navigation$NavigationDocument",
+        "SystemTexts"         => "Texts$SystemTextCollection",
+      }.freeze
+    end
+  end
+end