mxrb 0.1.0

data/docs/pt-BR/writing.md

@@ -0,0 +1,177 @@
+# Criação e edição de projetos
+
+**Português** · [English](../en-US/writing.md) · [Deutsch](../de-DE/writing.md)
+
+`mxrb generate` avalia uma definição Ruby e cria ou atualiza o MPR. Nomes
+Mendix são chaves estáveis, portanto reaplicar a definição não duplica units.
+
+Para iniciar em uma pasta vazia:
+
+```sh
+mxrb init vet_clinic
+cd vet_clinic
+bundle install
+bundle exec mxrb generate project.rb
+bundle exec mxrb validate VetClinic.mpr
+```
+
+`init` aceita snake_case ou PascalCase, cria `Gemfile`, `project.rb` e o módulo
+principal em `modules/VetClinic`. O scaffold inclui somente código próprio: o
+módulo `System` é implícito no Runtime; Administration e Atlas são módulos de
+marketplace. O comando aborta sem alterar nada quando o diretório já existe.
+
+Para adicionar outro módulo de aplicação a partir da raiz do projeto:
+
+```sh
+mxrb module new appointments
+```
+
+O comando cria `modules/Appointments`, reutiliza o mesmo scaffold de
+domain/application e conecta o `module.rb` no `project.rb`. A operação aborta
+atomicamente se o módulo já existir ou se o arquivo de projeto não puder ser
+atualizado. Use `--target DIR` ao executar fora da raiz do projeto.
+
+Os scaffolds de artefatos, apresentação, infraestrutura, testes, design e CI
+estão no [catálogo de scaffolds](scaffolds.md). Para entidades, consulte a
+[referência completa da DSL](entity-dsl.md).
+
+```ruby
+Mxrb.define("Shop.mpr") do
+  mendix_version "11.12.1"
+  self.module :Sales do
+    entity :Order do
+      string :Number, documentation: "Número estável do pedido"
+      decimal :Total, default: 0
+    end
+  end
+end
+```
+
+```sh
+bundle exec mxrb generate shop.rb
+bundle exec mxrb validate Shop.mpr
+bundle exec mxrb export Shop.mpr exported-shop
+bundle exec mxrb compare original.mpr rebuilt.mpr
+```
+
+## Avaliações de modelo
+
+```ruby
+artifact "Sales.Order", kind: :entity
+no_call_cycles
+no_missing_internal_references
+check("Order possui Total") do |project|
+  project.find_artifact("Sales.Order.Total", kind: :attribute)
+end
+```
+
+Execute com `mxrb evaluate App.mpr evaluation.rb`.
+
+## Testes funcionais
+
+```ruby
+microflow "cria pedido",
+          call: "Sales.ACT_CreateOrder",
+          before: { call: "Sales.TEST_Preparar" },
+          after: { call: "Sales.TEST_Limpar" },
+          expect: {
+            return: "true",
+            count: { entity: "Sales.Order", xpath: "[Status = 'Open']", equals: 1 }
+          }
+```
+
+Use `mxrb test App.mpr functional_test.rb`; acrescente `--docker` para executar
+JDK, MxBuild e Runtime em containers descartáveis. Use `--native` para executar
+o grafo do microflow no Runtime de modelo em Ruby, sem Java, `mx` ou `mxbuild`.
+O modo nativo cobre CRUD, variáveis, decisões, chamadas, agregações e logs em
+uma store transacional; Java, REST, UI e conectores ainda falham explicitamente
+e fazem rollback. Não há JUnit nem MDL. O MPR original nunca é alterado.
+Use `--json resultado.json` e/ou `--junit resultado.xml` para relatórios de CI.
+JUnit é apenas o formato XML de intercâmbio neste caso; o MXRB o grava
+diretamente em Ruby, sem instalar ou executar o framework Java JUnit.
+
+## Cobertura
+
+```sh
+bundle exec rspec
+MXRB_COVERAGE=1 bundle exec rspec
+```
+
+## Marketplace de módulos Ruby
+
+```sh
+mxrb module search
+mxrb module search security
+mxrb module add shared-kernel
+mxrb module add ./pacote-local --target ./projeto-exportado
+```
+
+Catálogos JSON podem vir da gem, de um caminho local ou de HTTPS com
+`--registry`. Pacotes possuem `mxrb-module.json` e podem ser embutidos,
+diretórios locais ou repositórios Git. A instalação usa staging, rejeita
+caminhos inseguros e grava `.mxrb/modules.lock.json` com versão, origem, ref e
+SHA-256 dos arquivos instalados.
+
+## Baseline nativo e estruturas profundas
+
+`mxrb export` grava `.mxrb/native_units.json` como baseline sem perdas e
+`.mxrb/native_units.rb` com cada payload BSON expandido em Hashes Ruby
+editáveis. Entradas `native_unit` expõem todos os campos de imagens, constantes,
+datasets, serviços, configurações, templates e tipos futuros; valores binários
+usam `bson_binary`. Alterações nesse Ruby sobrepõem o baseline antes das escritas
+tipadas. Corpos de flow possuem `body_fingerprint`: o grafo nativo é reutilizado
+quando o Ruby não mudou e regenerado após uma edição.
+
+A DSL cobre criação/alteração/retrieve/commit/delete, chamadas de microflow,
+Java, JavaScript, nanoflow e app service, páginas, REST, listas, decisões,
+loops, eventos de erro e rescue.
+
+## Páginas, navegação e segurança
+
+Controles core possuem métodos concisos: `text`, `text_box`, `number_input`,
+`text_area`, `check_box`, `date_picker`, `button`, `container`, `snippet` e
+`tab_control` com widgets dentro de cada `tab_page`. Esses controles usam o
+modelo Forms moderno do Mendix 11. `data_grid` gera Data Grid 2; `drop_down` e
+`reference_selector` geram Combo Box.
+
+Widgets pluggable precisam dos `.mpk` em `widgets/`. Depois de instalar os
+pacotes, sincronize o schema específico da versão e aplique as propriedades
+Ruby com:
+
+```bash
+bundle exec mxrb widgets sync project.rb MeuApp.mpr
+```
+
+Para outros MPKs existe `pluggable_widget`, com widget id e mapa de
+propriedades. Widgets importados ainda desconhecidos são preservados como
+`native_widget` e `deep_structure`, sem perder configuração no ciclo
+export/generate. Toda página importada também expõe `deep_structure({...})`.
+Menus combinam DSL curta e estrutura profunda.
+Project roles, module roles e `allowed_roles` são editáveis em Ruby.
+
+## MPR v2
+
+O manifesto registra `format_version: v2`; a geração cria automaticamente os
+arquivos `mprcontents/*.mxunit`.
+
+## Análise semântica
+
+```ruby
+project.references_to("Sales.Order")
+project.callers_of("Sales.Process")
+project.impact_of("Sales.Order")
+project.plan_rename("Sales.Order", to: "Invoice")
+project.plan_remove("Sales.FluxoSemUso")
+project.plan_move("Sales.Processar", to: "Sales.Automacao")
+project.analyze
+```
+
+Na CLI, use `refs`, `callers`, `callees`, `impact`, `rename`, `remove`, `move`,
+`lint`, `report`, `diff`, `find`, `describe` e `tree`. O lint nativo verifica
+acesso de entidades persistentes, papéis de páginas/flows, documentação de
+contratos públicos, alvos de navegação e mapeamentos duplicados de module role.
+Use `mxrb cache status|warm|clear app.mpr` para métricas e manutenção do índice.
+Refatorações apenas
+mostram a prévia, salvo quando `--apply` é informado. A remoção é bloqueada se
+houver referências recebidas ou units filhas; movimentos ficam no mesmo
+módulo e rejeitam ciclos de pastas.

data/examples/sudoku_evaluation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Executable model expectations: plain Ruby, no MDL.
+artifact "Sudoku.Game", kind: :entity
+artifact "Sudoku.Game_Play", kind: :page
+artifact "Sudoku.ACT_DealGame", kind: :microflow
+
+no_call_cycles
+no_missing_internal_references
+maximum_unreferenced 250, severity: :warning
+
+check "Sudoku exposes its three domain entities" do |project|
+  project.search_artifacts("Sudoku.", kind: :entity).size == 3
+end

data/examples/sudoku_functional_test.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# First functional slice: each microflow must complete without an unhandled
+# runtime exception. The source project is never modified.
+microflow "creates an easy game",
+          call: "Sudoku.ACT_NewEasy",
+          expect: {
+            count: [
+              { entity: "Sudoku.Game", equals: 1 },
+              { entity: "Sudoku.Cell", equals: 81 }
+            ]
+          }
+microflow "creates a medium game",
+          call: "Sudoku.ACT_NewMedium",
+          expect: {
+            count: [
+              { entity: "Sudoku.Game", equals: 2 },
+              { entity: "Sudoku.Cell", equals: 162 }
+            ]
+          }
+microflow "creates a hard game",
+          call: "Sudoku.ACT_NewHard",
+          expect: {
+            count: [
+              { entity: "Sudoku.Game", equals: 3 },
+              { entity: "Sudoku.Cell", equals: 243 }
+            ]
+          }

data/lib/mxrb/architecture/graph.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module Architecture
+    Node = Data.define(:id, :module_name, :kind, :name, :metadata)
+    Edge = Data.define(:from, :to, :relation, :metadata)
+
+    class Graph
+      attr_reader :nodes, :edges
+
+      def initialize(definition)
+        @definition = definition
+        @nodes = {}
+        @edges = []
+        build
+      end
+
+      def node_id(module_name, kind, name)
+        "#{module_name}::#{kind}::#{name}"
+      end
+
+      def find(module_name, kind, name)
+        @nodes[node_id(module_name, kind, name)]
+      end
+
+      def dependencies_of(node)
+        @edges.select { _1.from == node.id }.filter_map { @nodes[_1.to] }
+      end
+
+      private
+
+      def build
+        @definition.fetch(:modules).each do |mod|
+          add_module_nodes(mod)
+          add_module_edges(mod)
+        end
+      end
+
+      def add_module_nodes(mod)
+        module_name = mod.fetch(:name)
+        {
+          entity: mod.fetch(:entities),
+          page: mod.fetch(:pages),
+          microflow: mod.fetch(:microflows),
+          nanoflow: mod.fetch(:nanoflows, []),
+          repository: mod.fetch(:repositories, [])
+        }.each do |kind, items|
+          items.each { add_node(module_name, kind, _1.fetch(:name), _1) }
+        end
+      end
+
+      def add_module_edges(mod)
+        module_name = mod.fetch(:name)
+        mod.fetch(:entities).each do |entity|
+          from = id(module_name, :entity, entity.fetch(:name))
+          entity.fetch(:associations, []).each do |association|
+            add_edge(from, ref(module_name, :entity, association.fetch(:target)), :association)
+          end
+          Array(entity[:lifecycle]).each do |callback|
+            add_edge(from, ref(module_name, :microflow, callback.fetch(:handler)), callback.fetch(:event))
+          end
+        end
+
+        mod.fetch(:pages).each do |page|
+          from = id(module_name, :page, page.fetch(:name))
+          if (source = page[:data_source])
+            add_edge(from, ref(module_name, source.fetch(:kind), source.fetch(:name)), :data_source)
+          end
+          page.fetch(:events, []).each do |event|
+            next if event.fetch(:kind).to_sym == :action
+
+            add_edge(from, ref(module_name, event.fetch(:kind), event.fetch(:handler)), event.fetch(:event),
+                     target: event[:target])
+          end
+          page.fetch(:widgets, []).each do |widget|
+            widget.fetch(:events, []).each do |event|
+              next if event.fetch(:kind).to_sym == :action
+
+              add_edge(
+                from,
+                ref(module_name, event.fetch(:kind), event.fetch(:handler)),
+                event.fetch(:event),
+                target: widget.fetch(:name), widget_type: widget.fetch(:type)
+              )
+            end
+          end
+        end
+
+        (mod.fetch(:microflows) + mod.fetch(:nanoflows, [])).each do |flow|
+          from = id(module_name, flow.fetch(:runtime) == :client ? :nanoflow : :microflow, flow.fetch(:name))
+          flow.fetch(:calls, []).each do |call|
+            add_edge(from, ref(module_name, call.fetch(:kind), call.fetch(:name)), :calls)
+          end
+          flow.fetch(:repositories, []).each do |repository|
+            add_edge(from, ref(module_name, :repository, repository), :uses_repository)
+          end
+        end
+      end
+
+      def add_node(module_name, kind, name, metadata)
+        identifier = id(module_name, kind, name)
+        @nodes[identifier] = Node.new(identifier, module_name, kind, name, metadata)
+      end
+
+      def add_edge(from, to, relation, metadata = {})
+        @edges << Edge.new(from, to, relation.to_sym, metadata)
+      end
+
+      def id(module_name, kind, name)
+        node_id(module_name, kind, name)
+      end
+
+      def ref(current_module, kind, raw_name)
+        text = raw_name.to_s
+        if text.include?(".")
+          module_name, name = text.split(".", 2)
+          id(module_name, kind, name)
+        else
+          id(current_module, kind, text)
+        end
+      end
+    end
+  end
+end

data/lib/mxrb/architecture/validator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module Architecture
+    class Validator
+      Result = Data.define(:errors, :warnings) do
+        def valid? = errors.empty?
+      end
+
+      def initialize(graph)
+        @graph = graph
+      end
+
+      def validate
+        errors = []
+        warnings = []
+        validate_targets(errors)
+        validate_layers(errors)
+        validate_cycles(errors)
+        Result.new(errors.freeze, warnings.freeze)
+      end
+
+      def validate!
+        result = validate
+        return result if result.valid?
+
+        raise ValidationError, "architecture validation failed:\n- #{result.errors.join("\n- ")}"
+      end
+
+      private
+
+      def validate_targets(errors)
+        @graph.edges.each do |edge|
+          next if @graph.nodes.key?(edge.to)
+          next if late_bound_page_nanoflow?(edge)
+          next if platform_owned_target?(edge.to)
+
+          errors << "#{edge.from} #{edge.relation} references missing #{edge.to}"
+        end
+      end
+
+      def late_bound_page_nanoflow?(edge)
+        from = @graph.nodes[edge.from]
+        from&.kind == :page && edge.to.include?("::nanoflow::")
+      end
+
+      def platform_owned_target?(target)
+        target.start_with?("System::")
+      end
+
+      def validate_layers(errors)
+        @graph.edges.each do |edge|
+          from = @graph.nodes[edge.from]
+          to = @graph.nodes[edge.to]
+          next unless from && to
+
+          if from.kind == :page && to.kind == :repository
+            errors << "#{from.id} cannot access repository #{to.id} directly"
+          end
+          if from.kind == :entity && edge.relation.to_s.start_with?("on_") && to.kind == :nanoflow
+            errors << "#{from.id} lifecycle cannot call client-side #{to.id}"
+          end
+          # Entity-to-entity associations are allowed cross-module in Mendix domain model
+          next if edge.relation == :association && from.kind == :entity && to.kind == :entity
+          if from.module_name != to.module_name && !to.metadata.fetch(:public, false)
+            errors << "#{from.id} references internal artifact #{to.id} from another module"
+          end
+        end
+      end
+
+      def validate_cycles(errors)
+        adjacency = Hash.new { |h, k| h[k] = [] }
+        @graph.edges.select { %i[calls].include?(_1.relation) }.each do |edge|
+          adjacency[edge.from] << edge.to if @graph.nodes.key?(edge.to)
+        end
+        visiting = {}
+        visited = {}
+        stack = []
+
+        visit = lambda do |node|
+          return if visited[node]
+          if visiting[node]
+            start = stack.index(node) || 0
+            errors << "call cycle detected: #{(stack[start..] + [node]).join(' -> ')}"
+            return
+          end
+          visiting[node] = true
+          stack << node
+          adjacency[node].each { visit.call(_1) }
+          stack.pop
+          visiting.delete(node)
+          visited[node] = true
+        end
+        @graph.nodes.each_key { visit.call(_1) }
+      end
+    end
+  end
+end

data/lib/mxrb/benchmark.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mxrb
+  BenchmarkResult = Data.define(:iterations, :open_seconds, :index_seconds, :validate_seconds, :units)
+
+  # Repeatable wall-clock benchmark for the main read-only MPR operations.
+  class Benchmark
+    def initialize(path, iterations: 3, clock: Process.method(:clock_gettime))
+      @path = File.expand_path(path)
+      @iterations = Integer(iterations)
+      @clock = clock
+      raise ArgumentError, 'iterations must be between 1 and 100' unless (1..100).cover?(@iterations)
+    end
+
+    def run
+      open_time, units = measure { Mxrb.open(@path) { _1.all_units.size } }
+      index_time, = measure { Mxrb.open(@path) { _1.semantic_index.artifacts.size } }
+      validate_time, = measure { Mxrb.validate(@path).valid? }
+      BenchmarkResult.new(@iterations, open_time, index_time, validate_time, units)
+    end
+
+    private
+
+    def measure
+      value = nil
+      started = now
+      @iterations.times { value = yield }
+      [((now - started) / @iterations).round(6), value]
+    end
+
+    def now = @clock.call(Process::CLOCK_MONOTONIC)
+  end
+end