mxrb 0.1.0

data/lib/mxrb/functional.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+
+module Mxrb
+  module Functional
+    Hook = Data.define(:target, :arguments)
+    CountExpectation = Data.define(:entity, :xpath, :equals)
+    TestCase = Data.define(
+      :name, :target, :arguments, :timeout,
+      :expected_return, :counts, :setup, :cleanup
+    ) do
+      class << self
+        alias data_new new
+
+        def new(name, target, arguments, timeout, expected_return = nil,
+                counts = [].freeze, setup = nil, cleanup = nil)
+          data_new(
+            name, target, arguments, timeout,
+            expected_return, counts, setup, cleanup
+          )
+        end
+      end
+    end
+    Definition = Data.define(:tests) do
+      def empty? = tests.empty?
+    end
+    TestResult = Data.define(:name, :passed, :message) do
+      def passed? = passed
+      def failed? = !passed
+    end
+    Result = Data.define(:tests, :finished) do
+      def passed? = finished && tests.all?(&:passed?)
+      def finished? = finished
+      def failures = tests.select(&:failed?)
+    end
+
+    # Ruby-only definition of runtime microflow tests.
+    class Suite
+      attr_reader :tests
+
+      def initialize
+        @tests = []
+      end
+
+      def microflow(name, call:, pass: {}, timeout: 60, expect: {},
+                    before: nil, after: nil)
+        label = name.to_s.strip
+        target = call.to_s.strip
+        raise ArgumentError, "functional test name cannot be empty" if label.empty?
+        unless target.match?(/\A[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*\z/)
+          raise ArgumentError, "microflow call must be a qualified Mendix name"
+        end
+        raise ArgumentError, "functional test timeout must be positive" unless timeout.to_f.positive?
+
+        arguments = pass.to_h.transform_keys(&:to_s).transform_values(&:to_s).freeze
+        expectations = expect.to_h
+        expected_return = expectations[:return] || expectations["return"]
+        counts = normalize_counts(expectations[:count] || expectations["count"])
+        @tests << TestCase.new(
+          label, target, arguments, timeout.to_f, expected_return&.to_s,
+          counts, normalize_hook(before), normalize_hook(after)
+        )
+        self
+      end
+
+      def evaluate(path)
+        instance_eval(File.read(path), path, 1)
+        self
+      end
+
+      def definition
+        Definition.new(@tests.dup.freeze)
+      end
+
+      private
+
+      def normalize_hook(value)
+        return unless value
+
+        options = value.is_a?(Hash) ? value : { call: value }
+        target = (options[:call] || options["call"]).to_s
+        unless target.match?(/\A[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*\z/)
+          raise ArgumentError, "functional hook must call a qualified microflow"
+        end
+        arguments = (options[:pass] || options["pass"] || {}).to_h
+          .transform_keys(&:to_s).transform_values(&:to_s).freeze
+        Hook.new(target, arguments)
+      end
+
+      def normalize_counts(value)
+        values = value.is_a?(Array) ? value : [value]
+        values.compact.map do |item|
+          options = item.to_h
+          entity = (options[:entity] || options["entity"]).to_s
+          equals = options.key?(:equals) ? options[:equals] : options["equals"]
+          unless entity.match?(/\A[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*\z/)
+            raise ArgumentError, "count expectation requires a qualified entity"
+          end
+          raise ArgumentError, "count expectation requires a non-negative integer" unless
+            equals.is_a?(Integer) && equals >= 0
+
+          CountExpectation.new(
+            entity, (options[:xpath] || options["xpath"])&.to_s, equals
+          )
+        end.freeze
+      end
+    end
+
+    # Adds an isolated after-startup runner to a writable disposable MPR copy.
+    class Instrumenter
+      MODULE_NAME = "MxrbTests"
+      RUNNER_NAME = "RunAll"
+      LOG_NODE = "'MXRB_TEST'".freeze
+
+      def initialize(path, definition)
+        @path = File.expand_path(path)
+        @definition = definition
+      end
+
+      def instrument!
+        raise FunctionalTestError, "functional test suite is empty" if @definition.empty?
+
+        version = validate_targets!
+        mod = build_module
+        Writer.new(
+          @path,
+          version: version, modules: [mod.to_h],
+          security: nil, native_units_path: nil
+        ).write!
+        select_after_startup!
+        self
+      end
+
+      def runner = "#{MODULE_NAME}.#{RUNNER_NAME}"
+
+      private
+
+      def validate_targets!
+        Mxrb.open(@path) do |project|
+          @definition.tests.each do |test|
+            validate_call!(project, test.target, test.arguments)
+            validate_call!(project, test.setup.target, test.setup.arguments) if test.setup
+            validate_call!(project, test.cleanup.target, test.cleanup.arguments) if test.cleanup
+            test.counts.each do |expectation|
+              unless project.find_artifact(expectation.entity, kind: :entity)
+                raise FunctionalTestError, "entity #{expectation.entity} not found"
+              end
+            end
+          end
+          project.mendix_version
+        end
+      end
+
+      def validate_call!(project, target, arguments)
+        artifact = project.find_artifact(target, kind: :microflow)
+        raise FunctionalTestError, "microflow #{target} not found" unless artifact
+
+        doc = project.parse_bson(project.raw_unit(artifact.unit_id))
+        collection = doc["MicroflowParameterCollection"] || doc["Parameters"] || {}
+        parameter_docs = collection.is_a?(Hash) ?
+          IO::BsonCodec.parse_array(collection["Parameters"])[:items] : []
+        parameter_docs += IO::BsonCodec.parse_array(
+          doc.dig("ObjectCollection", "Objects")
+        )[:items].select { _1["$Type"] == "Microflows$MicroflowParameter" }
+        parameters = parameter_docs.filter_map do |parameter|
+          parameter["Name"] || parameter["name"] if parameter.is_a?(Hash)
+        end
+        unknown = arguments.keys - parameters
+        missing = parameters - arguments.keys
+        return if unknown.empty? && missing.empty?
+
+        raise FunctionalTestError,
+              "microflow #{target} arguments mismatch " \
+              "(missing: #{missing.join(', ')}, unknown: #{unknown.join(', ')})"
+      end
+
+      def build_module
+        mod = Dsl::ModuleBuilder.new(MODULE_NAME)
+        tests = @definition.tests
+        wrapper_names = tests.each_index.map { wrapper_name(_1) }
+        emit_hook = lambda do |flow, hook|
+          flow.call_microflow(hook.target, pass: hook.arguments) if hook
+        end
+        tests.each_with_index do |test, index|
+          mod.microflow(wrapper_name(index), kind: :test) do
+            return_type :Boolean
+            emit_hook.call(self, test.setup)
+            call_microflow(
+              test.target, pass: test.arguments,
+              as: (test.expected_return ? :mxrb_actual : nil)
+            )
+            conditions = []
+            conditions << "$mxrb_actual = #{test.expected_return}" if test.expected_return
+            test.counts.each_with_index do |expectation, count_index|
+              list = :"mxrb_items_#{count_index + 1}"
+              count = :"mxrb_count_#{count_index + 1}"
+              retrieve_objects expectation.entity, as: list, xpath: expectation.xpath
+              aggregate list, function: :count, as: count
+              conditions << "$#{count} = #{expectation.equals}"
+            end
+            if conditions.empty?
+              emit_hook.call(self, test.cleanup)
+              return_value "true"
+            else
+              emit_hook.call(self, test.cleanup)
+              return_value "(#{conditions.join(' and ')})"
+            end
+            rescue_all do
+              emit_hook.call(self, test.cleanup)
+              return_value "false"
+            end
+          end
+        end
+        mod.microflow(RUNNER_NAME, kind: :test) do
+          return_type :Boolean
+          tests.each_with_index do |test, index|
+            variable = :"passed_#{index + 1}"
+            call_microflow "#{MODULE_NAME}.#{wrapper_names.fetch(index)}", as: variable
+            decision "$#{variable}" do
+              on(true) do
+                log_message "[MXRB_TEST] PASS #{test.name}", node: LOG_NODE
+              end
+              on(false) do
+                log_message "[MXRB_TEST] FAIL #{test.name}", level: :error, node: LOG_NODE
+              end
+            end
+          end
+          log_message "[MXRB_TEST] DONE", node: LOG_NODE
+          return_value "true"
+        end
+        mod
+      end
+
+      def wrapper_name(index) = format("Test_%03d", index + 1)
+
+      def select_after_startup!
+        mpr = IO::MprFile.open(@path)
+        raw = mpr.all_units.find { mpr.parse_contents(_1)["$Type"] == "Settings$ProjectSettings" }
+        raise FunctionalTestError, "project settings unit not found" unless raw
+
+        doc = mpr.parse_contents(raw)
+        settings = IO::BsonCodec.parse_array(doc["Settings"])[:items]
+        model_settings = settings.find { _1["$Type"] == "Settings$ModelSettings" }
+        raise FunctionalTestError, "model settings part not found" unless model_settings
+
+        model_settings["AfterStartupMicroflow"] = runner
+        mpr.update_unit(raw.fetch("UnitID"), doc)
+      ensure
+        mpr&.close
+      end
+    end
+
+    class LogParser
+      PATTERN = /\[MXRB_TEST\] (PASS|FAIL) (.+)$/
+
+      def parse(text)
+        tests = text.each_line.filter_map do |line|
+          match = line.strip.match(PATTERN)
+          next unless match
+
+          passed = match[1] == "PASS"
+          TestResult.new(match[2], passed, passed ? "passed" : "microflow failed")
+        end
+        Result.new(tests.freeze, text.include?("[MXRB_TEST] DONE"))
+      end
+    end
+
+    class Reporter
+      def write_json(execution, path)
+        payload = {
+          passed: execution.passed?,
+          finished: execution.result.finished?,
+          elapsed: execution.elapsed,
+          tests: execution.result.tests.map do |test|
+            { name: test.name, passed: test.passed?, message: test.message }
+          end
+        }
+        File.write(path, JSON.pretty_generate(payload) << "\n")
+        path
+      end
+
+      def write_junit(execution, path)
+        tests = execution.result.tests
+        failures = tests.count(&:failed?)
+        cases = tests.map do |test|
+          name = CGI.escapeHTML(test.name)
+          if test.passed?
+            %(  <testcase name="#{name}"/>)
+          else
+            message = CGI.escapeHTML(test.message)
+            %(  <testcase name="#{name}"><failure message="#{message}"/></testcase>)
+          end
+        end.join("\n")
+        xml = <<~XML
+          <?xml version="1.0" encoding="UTF-8"?>
+          <testsuite name="mxrb" tests="#{tests.size}" failures="#{failures}" time="#{execution.elapsed}">
+          #{cases}
+          </testsuite>
+        XML
+        File.write(path, xml)
+        path
+      end
+    end
+  end
+end

data/lib/mxrb/github/annotator.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Mxrb
+  module Github
+    # Maps a Compare::Result to GitHub annotations.
+    #
+    # Supports two output modes:
+    #   1. GitHub Actions workflow commands (stdout lines) for CI annotation
+    #   2. `gh pr comment` for pull request review comments
+    #
+    # Usage:
+    #   result = Mxrb::Compare::Comparator.new(base_mpr, head_mpr).compare
+    #   ann = Mxrb::Github::Annotator.new(result, exported_dir: "out/", repo: "org/repo")
+    #   ann.print_actions_annotations          # write to stdout for GH Actions
+    #   ann.post_pr_comment!(pr_number: 42)   # post summary via gh CLI
+    class Annotator
+      # Maps Compare path segments to file-layer hints used in exported trees.
+      LAYER_MAP = {
+        "entities"   => "domain",
+        "attributes" => "domain",
+        "microflows" => "logic",
+        "nanoflows"  => "presentation",
+        "pages"      => "presentation",
+        "menus"      => "presentation",
+      }.freeze
+
+      Annotation = Data.define(:level, :title, :message, :file, :line)
+
+      def initialize(compare_result, exported_dir: nil, repo: nil)
+        @result       = compare_result
+        @exported_dir = exported_dir && File.expand_path(exported_dir)
+        @repo         = repo
+      end
+
+      # Returns an array of Annotation structs for each changed artifact.
+      def annotations
+        @annotations ||= @result.changes.map do |change|
+          build_annotation(change)
+        end
+      end
+
+      # Emits GitHub Actions workflow command lines to stdout.
+      # When run inside a GH Actions job these create inline PR annotations.
+      def print_actions_annotations(out: $stdout)
+        annotations.each do |ann|
+          file_part = ann.file ? "file=#{ann.file}" : ""
+          line_part = ann.line ? ",line=#{ann.line}" : ""
+          out.puts "::#{ann.level} #{file_part}#{line_part},title=#{ann.title}::#{ann.message}"
+        end
+      end
+
+      # Posts a Markdown summary comment to a GitHub PR via the `gh` CLI.
+      def post_pr_comment!(pr_number:, repo: @repo)
+        raise ArgumentError, "repo required (org/name)" unless repo
+        raise ArgumentError, "pr_number required" unless pr_number
+
+        body = build_comment_body
+        cmd  = ["gh", "pr", "comment", pr_number.to_s, "--repo", repo, "--body", body]
+        out, err, status = Open3.capture3(*cmd)
+        raise "gh pr comment failed: #{err}" unless status.success?
+
+        out.strip
+      end
+
+      # Returns the comment body Markdown string without posting it.
+      def comment_body
+        build_comment_body
+      end
+
+      private
+
+      def build_annotation(change)
+        op    = change.operation
+        path  = change.path
+        label = path.last.to_s
+        module_name = infer_module(change)
+
+        level   = op == :removed ? "warning" : (op == :added ? "notice" : "notice")
+        title   = "#{op.to_s.capitalize}: #{label}"
+        message = format_message(change)
+        file    = exported_file(path, module_name)
+        line    = find_line_in_file(file, label)
+
+        Annotation.new(level: level, title: title, message: message, file: file, line: line)
+      end
+
+      def format_message(change)
+        op = change.operation
+        path = change.path.join(" › ")
+        case op
+        when :added   then "Added: #{path}"
+        when :removed then "Removed: #{path}"
+        when :changed
+          before = change.before.inspect
+          after  = change.after.inspect
+          "Changed: #{path} (#{before} → #{after})"
+        end
+      end
+
+      def infer_module(change)
+        path = change.path
+        # Compare paths are [:modules, "ModuleName", :kind, "Name"]
+        return path[1].to_s if path.first.to_s == "modules" && path.size > 1
+
+        nil
+      end
+
+      def exported_file(path, module_name)
+        return nil unless @exported_dir && module_name
+
+        # Find the first path segment that maps to a layer
+        type_segment = path.find { LAYER_MAP.key?(_1.to_s) }
+        return nil unless type_segment
+
+        layer         = LAYER_MAP[type_segment.to_s]
+        type_idx      = path.index(type_segment)
+        artifact_name = path[type_idx + 1]&.to_s&.downcase || path.last.to_s.downcase
+
+        relative_path = {
+          "domain" => ["domain", "model.rb"],
+          "logic" => ["logic", "#{artifact_name}.rb"],
+          "presentation" => ["presentation", "#{artifact_name}.rb"]
+        }.fetch(layer)
+        File.join(@exported_dir, "modules", module_name, *relative_path)
+      end
+
+      def find_line_in_file(file, label)
+        return nil unless file && File.file?(file.to_s)
+
+        File.foreach(file).with_index(1) do |line, n|
+          return n if line.include?(label)
+        end
+        nil
+      end
+
+      def build_comment_body
+        lines = ["## MXRB Semantic Diff\n"]
+        lines << "| Operation | Artifact | Detail |"
+        lines << "|-----------|----------|--------|"
+
+        @result.changes.each do |change|
+          op    = change.operation.to_s.capitalize
+          path  = change.path.join(" › ")
+          detail = case change.operation
+                   when :changed then "`#{change.before}` → `#{change.after}`"
+                   else ""
+                   end
+          icon = { added: "✅", removed: "❌", changed: "✏️" }[change.operation] || "ℹ️"
+          lines << "| #{icon} #{op} | `#{path}` | #{detail} |"
+        end
+
+        lines << ""
+        lines << "_Generated by [MXRB](https://github.com/lucamykael/mxrb)_"
+        lines.join("\n")
+      end
+    end
+  end
+end