mxrb 0.1.0

data/lib/mxrb/compiler/legacy_data_grid_compiler.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Mxrb
+  module Compiler
+    # rubocop:disable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength
+    # Compiles the built-in Data Grid 1 widget to the Dojo web-client contract.
+    class LegacyDataGridCompiler
+      include ModelValues
+
+      SOURCE_TYPES = {
+        'Forms$GridDatabaseSource' => 'database',
+        'Forms$NewGridDatabaseSource' => 'database',
+        'Forms$GridXPathSource' => 'xpath',
+        'Forms$MicroflowSource' => 'microflow'
+      }.freeze
+      BUTTON_FUNCTIONS = {
+        'Forms$GridSearchButton' => 'ToggleSearch',
+        'Forms$DataGridSelectButton' => 'ReturnSelection',
+        'Forms$GridNewButton' => 'InsertNew',
+        'Forms$GridEditButton' => 'EditSelection',
+        'Forms$GridDeleteButton' => 'DeleteSelection',
+        'Forms$GridActionButton' => 'InvokeAction'
+      }.freeze
+
+      attr_reader :unsupported
+
+      def initialize(source, page_name, widget, language:, sequence:)
+        @source = source
+        @page_name = page_name
+        @widget = widget
+        @language = language
+        @sequence = sequence
+        @unsupported = []
+      end
+
+      def html
+        props = JSON.generate(properties)[1..-2]
+        attributes = {
+          'data-mendix-id' => widget_id, 'data-mendix-type' => 'mxui.widget.DataGrid',
+          'data-mendix-props' => props, 'class' => css_class, 'tabindex' => @widget['TabIndex'].to_i
+        }
+        "<div #{attributes.map { |key, value| "#{key}='#{escape(value)}'" }.join(' ')}></div>"
+      end
+
+      private
+
+      def properties
+        {
+          'friendlyId' => friendly_id, 'entity' => entity, 'schema' => entity_schema,
+          'config' => {
+            'locale' => @language, 'gridType' => 'Standalone',
+            'gridpresentation' => presentation, 'datasource' => datasource,
+            'searchOptions' => search_options, 'searchElements' => search_elements,
+            'controlBar' => control_bar, 'defaultButton' => default_button,
+            'griddata' => columns.map { compile_column(_1) }, 'plugins' => {}
+          }
+        }
+      end
+
+      def presentation
+        {
+          'rows' => @widget['NumberOfRows'].to_i, 'columns' => 1,
+          'controlbar' => @widget['IsControlBarVisible'] == true,
+          'pagingbar' => @widget['IsPagingEnabled'] == true,
+          'sortparams' => sort_items, 'searchbar' => !search_elements.empty?,
+          'waitforsearch' => data_source.dig('SearchBar', 'WaitForSearch') == true,
+          'selectionmode' => @widget['SelectionMode'].to_s.downcase,
+          'editable' => columns.any? { _1['Editable'] == true }, 'sortable' => true,
+          'refresh' => @widget['RefreshTime'].to_i, 'selectfirst' => @widget['SelectFirst'] == true,
+          'showemptyrows' => @widget['ShowEmptyRows'] == true
+        }
+      end
+
+      def datasource
+        type = SOURCE_TYPES[data_source['$Type']]
+        @unsupported << data_source['$Type'].to_s unless type
+        result = { 'friendlyId' => friendly_id, 'type' => type || 'unsupported', 'path' => entity }
+        constraint = data_source['XPathConstraint'].to_s
+        result['xpathConstraints'] = constraint if type == 'database' || !constraint.empty?
+        result['offlineConstraints'] = [] if type == 'database'
+        result['microflow'] = data_source.dig('MicroflowSettings', 'Microflow').to_s if type == 'microflow'
+        result
+      end
+
+      def search_options
+        kind = data_source.dig('SearchBar', 'Type').to_s
+        {
+          'searchBar' => !search_elements.empty?, 'toggleable' => kind.start_with?('Foldable'),
+          'toggledByDefault' => kind != 'FoldableOpen'
+        }
+      end
+
+      def search_elements
+        array(data_source.dig('SearchBar', 'NewButtons')).filter_map do |field|
+          unless %w[Forms$ComparisonSearchField Forms$DropDownSearchField].include?(field['$Type'])
+            @unsupported << field['$Type'].to_s
+            next
+          end
+
+          {
+            'searchInputName' => field['Name'].to_s, 'defaults' => default_search_value(field),
+            'defaultsParser' => 'Simple', 'caption' => translated(field['Caption']),
+            'path' => relative_attribute(attribute_path(field)),
+            'operator' => field.fetch('Operator', 'Equal').to_s.downcase
+          }
+        end
+      end
+
+      def control_bar
+        tools = buttons.each_with_index.map { |button, index| compile_button(button, index) }
+        {
+          'gridTools' => tools.map(&:first),
+          'gridActions' => tools.filter_map(&:last)
+        }
+      end
+
+      def compile_button(button, index)
+        id = "#{@sequence}_#{index}"
+        type = button['$Type'].to_s
+        function = BUTTON_FUNCTIONS[type]
+        @unsupported << type unless function
+        tool = {
+          'mxid' => id, 'friendlyId' => "#{@page_name}.#{button['Name']}",
+          'name' => button['Name'].to_s,
+          'caption' => { '$type' => 'textTemplate', 'text' => button_caption(button),
+                         'friendlyId' => "#{@page_name}.#{button['Name']}" },
+          'title' => translated(button['Tooltip']), 'cssClass' => button_class(button)
+        }
+        action = function && { 'keyValue' => id, 'gridFunction' => function }
+        params = button_params(button)
+        action['params'] = params if action && params
+        [tool, action]
+      end
+
+      def button_params(button)
+        case button['$Type']
+        when 'Forms$GridNewButton', 'Forms$GridEditButton'
+          { entity => { 'pageSettings' => page_settings(button['FormSettings']) } }
+        when 'Forms$GridActionButton'
+          { entity => { 'action' => client_action(button['Action']),
+                        'maintainSelection' => button['MaintainSelectionAfterMicroflow'] == true } }
+        end
+      end
+
+      def client_action(action)
+        case action&.fetch('$Type', nil)
+        when 'Forms$MicroflowAction'
+          microflow = action.dig('MicroflowSettings', 'Microflow').to_s
+          { 'type' => 'callMicroflow', 'hasParameter' => true,
+            'params' => { 'name' => microflow, 'validate' => 'view', 'applyTo' => 'selection' } }
+        when 'Forms$FormAction'
+          { 'type' => 'openPage', 'params' => page_settings(action['FormSettings']) }
+        when 'Forms$DeleteClientAction'
+          { 'type' => 'deleteObject', 'params' => { 'applyTo' => 'selection' } }
+        when 'Forms$NoAction', nil then { 'type' => 'noAction' }
+        else
+          @unsupported << action['$Type'].to_s
+          { 'type' => 'unsupported' }
+        end
+      end
+
+      def page_settings(settings)
+        form = settings&.fetch('Form', '').to_s
+        location = settings&.fetch('Location', '').to_s
+        result = {
+          'path' => "#{form.tr('.', '/')}.page.xml",
+          'location' => %w[Popup ModalPopup].include?(location) ? 'modal' : 'content'
+        }
+        target = @source.units_of('Forms$Page').find do |unit|
+          "#{unit.module_name}.#{unit.document['Name']}" == form
+        end
+        result['resizable'] = true if target&.document&.fetch('PopupResizable', false) == true
+        result
+      end
+
+      def default_button
+        pointer = IO::BsonCodec.extract_id(@widget.dig('ControlBar', 'DefaultButtonPointer'))
+        index = buttons.index { IO::BsonCodec.extract_id(_1['$ID']) == pointer }
+        return nil unless index
+
+        { 'clickType' => @widget['DefaultButtonTrigger'].to_s.downcase, 'mxid' => "#{@sequence}_#{index}" }
+      end
+
+      def compile_column(column)
+        path = relative_attribute(attribute_path(column))
+        {
+          'tag' => path, 'name' => column['Name'].to_s, 'editable' => column['Editable'] == true,
+          'render' => render_type(column),
+          'display' => { 'width' => "#{column['WidthValue'].to_i}%", 'string' => translated(column['Caption']) }
+        }
+      end
+
+      def sort_items
+        array(data_source.dig('SortBar', 'SortItems')).map do |item|
+          [relative_attribute(attribute_path(item)), item['SortOrder'].to_s.downcase.sub('ending', '')]
+        end
+      end
+
+      def entity
+        direct = data_source['EntityPath'] || data_source.dig('EntityRef', 'Entity')
+        direct.to_s.empty? ? attribute_path(columns.first).to_s.rpartition('.').first : direct.to_s
+      end
+
+      def entity_schema
+        IO::BsonCodec.extract_id(@widget['$ID']).to_s
+      end
+
+      def render_type(column)
+        format = column.dig('FormattingInfo', 'EnumFormat')
+        format == 'Image' ? 'EnumImage' : 'String'
+      end
+
+      def attribute_path(value)
+        value['AttributePath'] || value.dig('AttributeRef', 'Attribute')
+      end
+
+      def relative_attribute(path)
+        path.to_s.delete_prefix("#{entity}.")
+      end
+
+      def buttons
+        @buttons ||= begin
+          control = @widget['ControlBar'] || {}
+          [control['SearchButton'], *array(control['NewButtons'])].compact
+        end
+      end
+
+      def data_source = @widget['DataSource'] || {}
+      def columns = array(@widget['Columns'])
+      def friendly_id = "#{@page_name}.#{@widget['Name']}"
+      def widget_id = "#{@sequence}_#{buttons.length}"
+
+      def css_class
+        ['mx-datagrid', "mx-name-#{@widget['Name']}", @widget['Class']]
+          .map(&:to_s).reject(&:empty?).uniq.join(' ')
+      end
+
+      def translated(text)
+        items = array(text&.fetch('Items', nil))
+        items.find { _1['LanguageCode'] == @language }&.fetch('Text', '') ||
+          items.find { _1['LanguageCode'] == 'en_US' }&.fetch('Text', '') ||
+          items.first&.fetch('Text', '') || ''
+      end
+
+      def button_caption(button)
+        translated(button.dig('CaptionTemplate', 'Template'))
+      end
+
+      def button_class(button)
+        style = button['ButtonStyle'].to_s.downcase
+        "btn-#{style.empty? ? 'default' : style}"
+      end
+
+      def default_search_value(field)
+        value = field['DefaultValue']
+        value.nil? || value.to_s.empty? ? nil : value
+      end
+
+      def escape(value)
+        value.to_s.gsub('&', '&amp;').gsub("'", '&#39;').gsub('<', '&lt;').gsub('>', '&gt;')
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength
+  end
+end

data/lib/mxrb/compiler/legacy_page_builder.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+module Mxrb
+  module Compiler
+    LegacyPageBuild = Data.define(:directory, :files, :bytes, :unsupported_widgets)
+
+    # rubocop:disable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity
+    # Writes deterministic Dojo page XML for the built-in Data Grid 1 contract.
+    class LegacyPageBuilder
+      include ModelValues
+
+      # Model elements that own visible client widgets. Supporting a page means
+      # rendering these elements, not merely serializing their nested settings.
+      VISUAL_WIDGET_TYPES = %w[
+        Forms$ActionButton Forms$CheckBox Forms$DataGrid Forms$DataView Forms$DatePicker
+        Forms$DivContainer Forms$DropDown Forms$DynamicText Forms$ImageViewer Forms$Label
+        Forms$LayoutGrid Forms$ListView Forms$RadioButtonGroup Forms$ReferenceSelector
+        Forms$SnippetCallWidget Forms$StaticImageViewer Forms$TabControl Forms$TextArea
+        Forms$TextBox Forms$InputReferenceSetSelector CustomWidgets$CustomWidget
+      ].freeze
+
+      def initialize(source, web_root, profiles: [:dojo])
+        @source = source
+        @web_root = web_root
+        @profiles = profiles
+        @unsupported = Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      def build
+        pages = @source.units_of('Forms$Page')
+        layouts = @source.units_of('Forms$Layout')
+        languages.each do |language|
+          layouts.each { write_layout(_1, language) }
+          pages.each { write_page(_1, language) }
+        end
+        write_manifest
+        files = Dir.glob(File.join(@web_root, 'pages', '**', '*.xml')).select { File.file?(_1) }
+        LegacyPageBuild.new(
+          directory: File.join(@web_root, 'pages'), files: files.length,
+          bytes: files.sum { File.size(_1) }, unsupported_widgets: frozen_unsupported
+        )
+      end
+
+      # Performs the same widget audit as #build without writing deployment files.
+      def audit
+        @unsupported.clear
+        (@source.units_of('Forms$Layout') + @source.units_of('Forms$Page')).each do |unit|
+          name = "#{unit.module_name}.#{unit.document['Name']}"
+          audit_unsupported_widgets(unit.document, name)
+          descendants(unit.document).select { _1['$Type'] == 'Forms$DataGrid' }.each_with_index do |grid, index|
+            compiler = LegacyDataGridCompiler.new(@source, name, grid, language: 'en_US', sequence: index + 1)
+            compiler.html
+            @unsupported[name].concat(compiler.unsupported)
+          end
+        end
+        frozen_unsupported
+      end
+
+      private
+
+      def write_page(unit, language)
+        name = "#{unit.module_name}.#{unit.document['Name']}"
+        audit_unsupported_widgets(unit.document, name)
+        @widget_sequence = 0
+        rendered = page_widgets(unit.document).map { render_widget(_1, name, language) }.join
+        path = File.join(@web_root, 'pages', language, unit.module_name, "#{unit.document['Name']}.page.xml")
+        FileUtils.mkdir_p(File.dirname(path))
+        File.binwrite(path, page_xml(unit, language, rendered))
+      end
+
+      def write_layout(unit, language)
+        name = "#{unit.module_name}.#{unit.document['Name']}"
+        audit_unsupported_widgets(unit.document, name)
+        @widget_sequence = 0
+        rendered = layout_widgets(unit.document).map { render_widget(_1, name, language) }.join
+        path = File.join(@web_root, 'pages', language, unit.module_name, "#{unit.document['Name']}.layout.xml")
+        FileUtils.mkdir_p(File.dirname(path))
+        File.binwrite(path, layout_xml(unit, rendered))
+      end
+
+      def audit_unsupported_widgets(root, page_name)
+        visit = lambda do |value|
+          case value
+          when Hash
+            type = value['$Type'].to_s
+            if type == 'Forms$DataGrid'
+              return
+            elsif VISUAL_WIDGET_TYPES.include?(type) && !supported_widget_type?(type)
+              @unsupported[page_name] << type
+            elsif type == 'Forms$DynamicText' && !array(value.dig('Content', 'Parameters')).empty?
+              @unsupported[page_name] << 'Forms$DynamicText(parameters)'
+            elsif type == 'Forms$DivContainer'
+              action_type = value.dig('OnClickAction', '$Type').to_s
+              @unsupported[page_name] << 'Forms$DivContainer(onClick)' \
+                unless action_type.empty? || action_type == 'Forms$NoAction'
+            end
+
+            value.each_value { visit.call(_1) }
+          when Array then value.each { visit.call(_1) }
+          end
+        end
+        visit.call(root)
+      end
+
+      def page_xml(unit, language, content)
+        page = unit.document
+        title = translated(page['Title'], language)
+        layout = page.dig('FormCall', 'Form').to_s.tr('.', '/')
+        argument = array(page.dig('FormCall', 'Arguments')).first
+        parameter = layout_argument_id(argument&.fetch('Parameter', '').to_s)
+        css = page_css_classes(page)
+        class_attribute = css.empty? ? '' : " class='#{escape(css)}'"
+        "\uFEFF<?xml version='1.0' encoding='utf-8'?>" \
+          "<m:page id='#{unit.id}' xmlns='http://www.w3.org/1999/xhtml' " \
+          "title='#{escape(title)}'#{class_attribute} xmlns:m='http://schemas.mendix.com/forms/1.0'>" \
+          "<m:layouts>#{layout.empty? ? '' : "<m:layout path='#{escape(layout)}.layout.xml'></m:layout>"}</m:layouts>" \
+          "<m:arguments><m:argument parameterName='#{escape(parameter)}'>#{content}</m:argument></m:arguments>" \
+          '</m:page>'
+      end
+
+      def layout_xml(unit, content)
+        "\uFEFF<?xml version='1.0' encoding='utf-8'?>" \
+          "<m:layout id='#{unit.id}' xmlns='http://www.w3.org/1999/xhtml' " \
+          "xmlns:m='http://schemas.mendix.com/forms/1.0'>" \
+          "<m:arguments><m:argument>#{content}</m:argument></m:arguments></m:layout>"
+      end
+
+      def render_widget(widget, page_name, language)
+        return '' unless widget.is_a?(Hash)
+
+        case widget['$Type']
+        when 'Forms$VerticalFlow'
+          widget_children(widget).map { render_widget(_1, page_name, language) }.join
+        when 'Forms$Placeholder'
+          identifier = IO::BsonCodec.extract_id(widget['$ID']) || widget['Name'].to_s
+          "<div data-mx-placeholder='#{escape(identifier)}' class='mx-placeholder'></div>"
+        when 'Forms$DivContainer'
+          render_container(widget, page_name, language)
+        when 'Forms$DynamicText'
+          render_dynamic_text(widget, language)
+        when 'Forms$DataGrid'
+          render_data_grid(widget, page_name, language)
+        else
+          ''
+        end
+      end
+
+      def render_container(widget, page_name, language)
+        children = widget_children(widget).map { render_widget(_1, page_name, language) }.join
+        tag = widget['RenderMode'].to_s == 'Span' ? 'span' : 'div'
+        "<#{tag}#{html_attributes(widget, base: nil)}>#{children}</#{tag}>"
+      end
+
+      def render_dynamic_text(widget, language)
+        content = widget['Content'] || {}
+        text = translated(content['Template'], language)
+        text = translated(content['Fallback'], language) if text.empty?
+        tag = widget['RenderMode'].to_s == 'Paragraph' ? 'p' : 'span'
+        attributes = html_attributes(widget, base: 'mx-text', mendix_id: next_widget_id)
+        "<#{tag}#{attributes}>#{escape(text)}</#{tag}>"
+      end
+
+      def render_data_grid(widget, page_name, language)
+        compiler = LegacyDataGridCompiler.new(
+          @source, page_name, widget, language:, sequence: next_widget_sequence
+        )
+        compiler.html.tap { @unsupported[page_name].concat(compiler.unsupported) }
+      end
+
+      def html_attributes(widget, base:, mendix_id: nil)
+        values = {}
+        css = css_classes(widget, base:)
+        values['class'] = css unless css.empty?
+        style = widget['Style'].to_s
+        style = widget.dig('Appearance', 'Style').to_s if style.empty?
+        values['style'] = style unless style.empty?
+        values['data-mendix-id'] = mendix_id if mendix_id
+        values.map { |key, value| " #{key}='#{escape(value)}'" }.join
+      end
+
+      def css_classes(widget, base:)
+        name = widget['Name'].to_s
+        classes = [base, ("mx-name-#{name}" unless name.empty?), widget['Class'],
+                   widget.dig('Appearance', 'Class')]
+        classes.compact.flat_map { _1.to_s.split }.reject(&:empty?).uniq.join(' ')
+      end
+
+      def page_css_classes(page)
+        layout = layout_unit(page.dig('FormCall', 'Form').to_s)&.document || {}
+        [layout['Class'], layout.dig('Appearance', 'Class'), page['Class'],
+         page.dig('Appearance', 'Class')].compact.flat_map { _1.to_s.split }
+                                         .reject(&:empty?).uniq.join(' ')
+      end
+
+      def page_widgets(document)
+        argument = array(document.dig('FormCall', 'Arguments')).first
+        widget_children(argument || document)
+      end
+
+      def layout_widgets(document) = widget_children(document)
+
+      def widget_children(value)
+        return [] unless value.is_a?(Hash)
+
+        plural = array(value['Widgets'])
+        singular = value['Widget']
+        plural.empty? && singular.is_a?(Hash) ? [singular] : plural
+      end
+
+      def supported_widget_type?(type)
+        %w[Forms$DataGrid Forms$DivContainer Forms$DynamicText].include?(type)
+      end
+
+      def layout_argument_id(parameter)
+        module_name, layout_name, placeholder_name = parameter.split('.', 3)
+        return parameter unless placeholder_name
+
+        layout = layout_unit("#{module_name}.#{layout_name}")
+        placeholder = descendants(layout&.document || {}).find do |value|
+          value['$Type'] == 'Forms$Placeholder' && value['Name'] == placeholder_name
+        end
+        IO::BsonCodec.extract_id(placeholder&.fetch('$ID', nil)) || parameter
+      end
+
+      def layout_unit(qualified_name)
+        module_name, layout_name = qualified_name.split('.', 2)
+        @source.units_of('Forms$Layout').find do |unit|
+          unit.module_name == module_name && unit.document['Name'] == layout_name
+        end
+      end
+
+      def next_widget_sequence
+        @widget_sequence += 1
+      end
+
+      def next_widget_id = "1_#{next_widget_sequence - 1}"
+
+      def descendants(root)
+        result = []
+        visit = lambda do |value|
+          case value
+          when Hash
+            result << value if value['$Type']
+            value.each_value { visit.call(_1) }
+          when Array then value.each { visit.call(_1) }
+          end
+        end
+        visit.call(root)
+        result
+      end
+
+      def languages
+        found = @source.documents.flat_map do |document|
+          descendants(document).filter_map do |value|
+            value['LanguageCode'].to_s if value['$Type'] == 'Texts$Translation'
+          end
+        end.reject(&:empty?).uniq.sort
+        found.empty? ? ['en_US'] : found
+      end
+
+      def translated(text, language)
+        items = array(text&.fetch('Items', nil))
+        items.find { _1['LanguageCode'] == language }&.fetch('Text', '') ||
+          items.find { _1['LanguageCode'] == 'en_US' }&.fetch('Text', '') || ''
+      end
+
+      def write_manifest
+        manifest = { 'profiles' => @profiles.map(&:to_s), 'unsupportedWidgets' => frozen_unsupported }
+        File.write(File.join(@web_root, 'mxrb-legacy-pages.json'), JSON.pretty_generate(manifest))
+      end
+
+      def frozen_unsupported
+        @unsupported.transform_values { _1.reject(&:empty?).uniq.sort }.freeze
+      end
+
+      def escape(value)
+        value.to_s.gsub('&', '&amp;').gsub("'", '&#39;').gsub('<', '&lt;').gsub('>', '&gt;')
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/MethodLength, Metrics/PerceivedComplexity
+  end
+end

data/lib/mxrb/compiler/mda.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'zip'
+
+module Mxrb
+  module Compiler
+    # Safe inspection and content-level comparison of Mendix deployment archives.
+    module Mda
+      Entry = Data.define(:path, :size, :crc, :sha256, :directory)
+      Inspection = Data.define(:path, :metadata, :entries, :sha256) do
+        def files = entries.reject(&:directory)
+        def roots = entries.map { _1.path.split('/').first }.uniq.sort
+      end
+      Difference = Data.define(:path, :status, :left_sha256, :right_sha256)
+
+      module_function
+
+      def inspect(path)
+        archive_path = File.expand_path(path)
+        entries = read_entries(archive_path)
+        metadata_entry = entries.find { _1.path == 'model/metadata.json' }
+        metadata = read_metadata(archive_path, metadata_entry)
+        raise CompilationError, 'MDA has no model/metadata.json' unless metadata
+
+        build_inspection(archive_path, metadata, entries)
+      rescue Zip::Error, JSON::ParserError => e
+        raise CompilationError, "invalid MDA #{archive_path}: #{e.message}"
+      end
+
+      def compare(left, right)
+        left_entries = entry_map(left)
+        right_entries = entry_map(right)
+        (left_entries.keys | right_entries.keys).sort.filter_map do |path|
+          lhs = left_entries[path]
+          rhs = right_entries[path]
+          status = difference_status(lhs, rhs)
+          next unless status
+
+          Difference.new(path:, status:, left_sha256: lhs&.sha256, right_sha256: rhs&.sha256)
+        end
+      end
+
+      def read_entries(archive_path)
+        Zip::File.open(archive_path) do |archive|
+          archive.map { build_entry(_1) }
+        end
+      end
+
+      def build_inspection(path, metadata, entries)
+        Inspection.new(
+          path:, metadata:, entries: entries.sort_by(&:path),
+          sha256: Digest::SHA256.file(path).hexdigest
+        )
+      end
+
+      def build_entry(entry)
+        path = safe_path(entry.name)
+        directory = entry.directory?
+        bytes = directory ? '' : entry.get_input_stream.read
+        Entry.new(
+          path:, size: entry.size, crc: entry.crc,
+          sha256: directory ? nil : Digest::SHA256.hexdigest(bytes), directory:
+        )
+      end
+
+      def read_metadata(archive_path, entry)
+        return unless entry
+
+        Zip::File.open(archive_path) do |archive|
+          JSON.parse(archive.get_entry(entry.path).get_input_stream.read)
+        end
+      end
+
+      def entry_map(path)
+        inspect(path).files.to_h { [_1.path, _1] }
+      end
+
+      def difference_status(left, right)
+        return :added unless left
+        return :removed unless right
+        return :changed if left.sha256 != right.sha256
+
+        nil
+      end
+
+      def safe_path(path)
+        clean = path.to_s.tr('\\', '/').sub(%r{\A/+}, '')
+        parts = clean.split('/')
+        if clean.empty? || parts.include?('..') || parts.include?('.')
+          raise CompilationError, "unsafe MDA entry #{path.inspect}"
+        end
+
+        clean
+      end
+    end
+  end
+end