RubyGems - mxrb - Versions diffs - 0.1.0 - Mend

mxrb 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (237) hide show

checksums.yaml +7 -0
data/LICENSE +21 -0
data/README.de-DE.md +108 -0
data/README.md +172 -0
data/README.pt-BR.md +109 -0
data/bin/mxrb +1613 -0
data/docs/README.md +10 -0
data/docs/de-DE/README.md +24 -0
data/docs/de-DE/architectural-patterns.md +26 -0
data/docs/de-DE/architectural-standard.md +48 -0
data/docs/de-DE/architecture.md +76 -0
data/docs/de-DE/compiler.md +162 -0
data/docs/de-DE/conventions.md +19 -0
data/docs/de-DE/design-system.md +52 -0
data/docs/de-DE/entity-dsl.md +53 -0
data/docs/de-DE/native-runtime-quality-report.md +74 -0
data/docs/de-DE/oql-sql.md +211 -0
data/docs/de-DE/platform-api-integration.md +36 -0
data/docs/de-DE/platform-operations.md +243 -0
data/docs/de-DE/project-structure.md +32 -0
data/docs/de-DE/ruby-first-roadmap.md +116 -0
data/docs/de-DE/scaffolds.md +59 -0
data/docs/de-DE/semantic-refactoring.md +56 -0
data/docs/de-DE/team-server.md +33 -0
data/docs/de-DE/validation-matrix.md +64 -0
data/docs/de-DE/vetclinic-acceptance.md +24 -0
data/docs/de-DE/writing.md +138 -0
data/docs/en-US/README.md +24 -0
data/docs/en-US/architectural-patterns.md +151 -0
data/docs/en-US/architectural-standard.md +89 -0
data/docs/en-US/architecture.md +170 -0
data/docs/en-US/compiler.md +157 -0
data/docs/en-US/conventions.md +82 -0
data/docs/en-US/design-system.md +163 -0
data/docs/en-US/entity-dsl.md +53 -0
data/docs/en-US/native-runtime-quality-report.md +73 -0
data/docs/en-US/oql-sql.md +201 -0
data/docs/en-US/platform-api-integration.md +36 -0
data/docs/en-US/platform-operations.md +244 -0
data/docs/en-US/project-structure.md +49 -0
data/docs/en-US/ruby-first-roadmap.md +186 -0
data/docs/en-US/scaffolds.md +57 -0
data/docs/en-US/semantic-refactoring.md +198 -0
data/docs/en-US/team-server.md +32 -0
data/docs/en-US/validation-matrix.md +257 -0
data/docs/en-US/vetclinic-acceptance.md +23 -0
data/docs/en-US/writing.md +655 -0
data/docs/pt-BR/README.md +24 -0
data/docs/pt-BR/architectural-patterns.md +25 -0
data/docs/pt-BR/architectural-standard.md +533 -0
data/docs/pt-BR/architecture.md +300 -0
data/docs/pt-BR/compiler.md +162 -0
data/docs/pt-BR/conventions.md +19 -0
data/docs/pt-BR/design-system.md +65 -0
data/docs/pt-BR/entity-dsl.md +116 -0
data/docs/pt-BR/native-runtime-quality-report.md +73 -0
data/docs/pt-BR/oql-sql.md +208 -0
data/docs/pt-BR/platform-api-integration.md +36 -0
data/docs/pt-BR/platform-operations.md +260 -0
data/docs/pt-BR/project-structure.md +32 -0
data/docs/pt-BR/ruby-first-roadmap.md +239 -0
data/docs/pt-BR/scaffolds.md +104 -0
data/docs/pt-BR/semantic-refactoring.md +55 -0
data/docs/pt-BR/team-server.md +59 -0
data/docs/pt-BR/validation-matrix.md +86 -0
data/docs/pt-BR/vetclinic-acceptance.md +50 -0
data/docs/pt-BR/writing.md +177 -0
data/examples/sudoku_evaluation.rb +14 -0
data/examples/sudoku_functional_test.rb +28 -0
data/lib/mxrb/architecture/graph.rb +124 -0
data/lib/mxrb/architecture/validator.rb +98 -0
data/lib/mxrb/benchmark.rb +33 -0
data/lib/mxrb/compare.rb +390 -0
data/lib/mxrb/compiler/adapter.rb +96 -0
data/lib/mxrb/compiler/artifact_document_compiler.rb +102 -0
data/lib/mxrb/compiler/artifact_materializer.rb +53 -0
data/lib/mxrb/compiler/client_model_materializer.rb +42 -0
data/lib/mxrb/compiler/code_action_document_compiler.rb +64 -0
data/lib/mxrb/compiler/code_action_materializer.rb +35 -0
data/lib/mxrb/compiler/code_action_type_compiler.rb +32 -0
data/lib/mxrb/compiler/combo_box_bundle_compiler.rb +314 -0
data/lib/mxrb/compiler/compatibility_analyzer.rb +169 -0
data/lib/mxrb/compiler/constants_materializer.rb +111 -0
data/lib/mxrb/compiler/data_grid_bundle_compiler.rb +290 -0
data/lib/mxrb/compiler/database_connector_action_compiler.rb +280 -0
data/lib/mxrb/compiler/deployment_asset_copier.rb +60 -0
data/lib/mxrb/compiler/deployment_bootstrapper.rb +208 -0
data/lib/mxrb/compiler/deployment_materializer.rb +43 -0
data/lib/mxrb/compiler/deployment_metadata.rb +64 -0
data/lib/mxrb/compiler/domain_document_compiler.rb +153 -0
data/lib/mxrb/compiler/domain_model_materializer.rb +35 -0
data/lib/mxrb/compiler/domain_security_compiler.rb +82 -0
data/lib/mxrb/compiler/gallery_bundle_compiler.rb +190 -0
data/lib/mxrb/compiler/generic_widget_bundle_compiler.rb +281 -0
data/lib/mxrb/compiler/image_bundle_compiler.rb +216 -0
data/lib/mxrb/compiler/java_proxy_generator.rb +509 -0
data/lib/mxrb/compiler/legacy_data_grid_compiler.rb +267 -0
data/lib/mxrb/compiler/legacy_page_builder.rb +287 -0
data/lib/mxrb/compiler/mda.rb +99 -0
data/lib/mxrb/compiler/microflow_document_compiler.rb +85 -0
data/lib/mxrb/compiler/microflow_materializer.rb +48 -0
data/lib/mxrb/compiler/microflow_node_compiler.rb +250 -0
data/lib/mxrb/compiler/model_package.rb +116 -0
data/lib/mxrb/compiler/model_values.rb +67 -0
data/lib/mxrb/compiler/nanoflow_program_compiler.rb +483 -0
data/lib/mxrb/compiler/navigation_document_compiler.rb +93 -0
data/lib/mxrb/compiler/packager.rb +100 -0
data/lib/mxrb/compiler/page_bundle_builder.rb +56 -0
data/lib/mxrb/compiler/page_bundle_compiler.rb +2004 -0
data/lib/mxrb/compiler/page_document_compiler.rb +77 -0
data/lib/mxrb/compiler/portable_packager.rb +356 -0
data/lib/mxrb/compiler/project_jar_archive.rb +84 -0
data/lib/mxrb/compiler/project_jar_builder.rb +121 -0
data/lib/mxrb/compiler/project_materializer.rb +139 -0
data/lib/mxrb/compiler/project_model_orderer.rb +52 -0
data/lib/mxrb/compiler/runtime_data_types.rb +31 -0
data/lib/mxrb/compiler/runtime_model_schema.rb +90 -0
data/lib/mxrb/compiler/schemas/runtime-10.24.0.73019.json +1052 -0
data/lib/mxrb/compiler/schemas/runtime-11.json +1215 -0
data/lib/mxrb/compiler/schemas/runtime-6.10.8.json +1148 -0
data/lib/mxrb/compiler/schemas/runtime-7.17.0.json +1144 -0
data/lib/mxrb/compiler/schemas/runtime-7.5.0.json +1215 -0
data/lib/mxrb/compiler/schemas/runtime-9.6.1.29396.json +868 -0
data/lib/mxrb/compiler/schemas/system-model-10.24.0.73019.b64 +1135 -0
data/lib/mxrb/compiler/schemas/system-model-11.12.1.b64 +815 -0
data/lib/mxrb/compiler/schemas/system-model-6.10.8.b64 +497 -0
data/lib/mxrb/compiler/schemas/system-model-7.17.0.b64 +519 -0
data/lib/mxrb/compiler/schemas/system-model-7.5.0.b64 +504 -0
data/lib/mxrb/compiler/schemas/system-model-9.6.1.29396.b64 +816 -0
data/lib/mxrb/compiler/security_materializer.rb +104 -0
data/lib/mxrb/compiler/settings_document_compiler.rb +45 -0
data/lib/mxrb/compiler/settings_materializer.rb +25 -0
data/lib/mxrb/compiler/source_model.rb +128 -0
data/lib/mxrb/compiler/system_model_seed.rb +88 -0
data/lib/mxrb/compiler/system_queue_materializer.rb +54 -0
data/lib/mxrb/compiler/system_text_materializer.rb +49 -0
data/lib/mxrb/compiler/translation_materializer.rb +95 -0
data/lib/mxrb/compiler/web_bundle_builder.rb +155 -0
data/lib/mxrb/compiler/web_list_data_source.rb +139 -0
data/lib/mxrb/compiler/web_operation_compiler.rb +614 -0
data/lib/mxrb/compiler/web_shell_materializer.rb +194 -0
data/lib/mxrb/compiler/widget_package_extractor.rb +63 -0
data/lib/mxrb/doctor.rb +116 -0
data/lib/mxrb/dsl/builder.rb +1636 -0
data/lib/mxrb/errors.rb +18 -0
data/lib/mxrb/evaluation.rb +131 -0
data/lib/mxrb/exporter.rb +1716 -0
data/lib/mxrb/frontend/migrator.rb +775 -0
data/lib/mxrb/functional.rb +307 -0
data/lib/mxrb/github/annotator.rb +161 -0
data/lib/mxrb/initializer.rb +257 -0
data/lib/mxrb/integrity/validator.rb +136 -0
data/lib/mxrb/io/bson_codec.rb +145 -0
data/lib/mxrb/io/mpr_file.rb +558 -0
data/lib/mxrb/io/mxunit_codec.rb +42 -0
data/lib/mxrb/marketplace.rb +380 -0
data/lib/mxrb/model/association.rb +98 -0
data/lib/mxrb/model/attribute.rb +100 -0
data/lib/mxrb/model/connector.rb +17 -0
data/lib/mxrb/model/design_materializer.rb +133 -0
data/lib/mxrb/model/design_migration.rb +126 -0
data/lib/mxrb/model/design_system.rb +111 -0
data/lib/mxrb/model/domain_model.rb +51 -0
data/lib/mxrb/model/entity.rb +180 -0
data/lib/mxrb/model/menu.rb +38 -0
data/lib/mxrb/model/microflow.rb +100 -0
data/lib/mxrb/model/module.rb +142 -0
data/lib/mxrb/model/navigation.rb +127 -0
data/lib/mxrb/model/page.rb +410 -0
data/lib/mxrb/model/project.rb +187 -0
data/lib/mxrb/model/unit.rb +48 -0
data/lib/mxrb/module_initializer.rb +75 -0
data/lib/mxrb/official_marketplace/content_api.rb +292 -0
data/lib/mxrb/official_marketplace/dependency_resolver.rb +329 -0
data/lib/mxrb/official_marketplace/lifecycle.rb +367 -0
data/lib/mxrb/official_marketplace/module_package_importer.rb +318 -0
data/lib/mxrb/official_marketplace/widget_package_installer.rb +414 -0
data/lib/mxrb/official_marketplace.rb +720 -0
data/lib/mxrb/oql/analyzer.rb +155 -0
data/lib/mxrb/oql/index_advisor.rb +85 -0
data/lib/mxrb/oql/plan_analyzer.rb +185 -0
data/lib/mxrb/oql/server.rb +132 -0
data/lib/mxrb/oql/sql_server_plan_analyzer.rb +190 -0
data/lib/mxrb/oql/sql_server_workload_analyzer.rb +80 -0
data/lib/mxrb/oql/workload_analyzer.rb +175 -0
data/lib/mxrb/oql/workload_baseline.rb +60 -0
data/lib/mxrb/oql.rb +424 -0
data/lib/mxrb/project_lifecycle.rb +76 -0
data/lib/mxrb/protocols/plan.rb +86 -0
data/lib/mxrb/protocols.rb +123 -0
data/lib/mxrb/runtime/database_workspace.rb +677 -0
data/lib/mxrb/runtime/docker_executor.rb +41 -0
data/lib/mxrb/runtime/docker_workspace.rb +29 -0
data/lib/mxrb/runtime/executor.rb +169 -0
data/lib/mxrb/runtime/java_locator.rb +26 -0
data/lib/mxrb/runtime/native.rb +474 -0
data/lib/mxrb/runtime/sql_server_database.rb +146 -0
data/lib/mxrb/runtime/toolchain.rb +82 -0
data/lib/mxrb/scaffold/cli.rb +113 -0
data/lib/mxrb/scaffold/generator.rb +246 -0
data/lib/mxrb/scaffold/help.rb +80 -0
data/lib/mxrb/scaffold/page_templates.rb +54 -0
data/lib/mxrb/scaffold/recipes.rb +198 -0
data/lib/mxrb/scaffold/registry.rb +82 -0
data/lib/mxrb/scaffold/templates.rb +723 -0
data/lib/mxrb/scaffold/transaction.rb +84 -0
data/lib/mxrb/schema/tables.rb +55 -0
data/lib/mxrb/semantic/analyzer.rb +473 -0
data/lib/mxrb/semantic/batch_plan.rb +68 -0
data/lib/mxrb/semantic/domain_mutator.rb +419 -0
data/lib/mxrb/semantic/embedder.rb +51 -0
data/lib/mxrb/semantic/extractor.rb +290 -0
data/lib/mxrb/semantic/index.rb +623 -0
data/lib/mxrb/semantic/inliner.rb +216 -0
data/lib/mxrb/semantic/mover.rb +153 -0
data/lib/mxrb/semantic/onnx_embedder.rb +34 -0
data/lib/mxrb/semantic/remover.rb +70 -0
data/lib/mxrb/semantic/renamer.rb +211 -0
data/lib/mxrb/semantic/tfidf_embedder.rb +46 -0
data/lib/mxrb/semantic/vec_store.rb +75 -0
data/lib/mxrb/team_server.rb +390 -0
data/lib/mxrb/templates/project/10.24.0.73019.json +32 -0
data/lib/mxrb/templates/project/11.12.1.json +32 -0
data/lib/mxrb/templates/project/6.10.8.json +50 -0
data/lib/mxrb/templates/project/7.17.0.json +50 -0
data/lib/mxrb/templates/project/7.5.0.json +50 -0
data/lib/mxrb/templates/project/9.6.1.29396.json +50 -0
data/lib/mxrb/version.rb +5 -0
data/lib/mxrb/widget_package.rb +338 -0
data/lib/mxrb/widget_synchronizer.rb +31 -0
data/lib/mxrb/writer.rb +3775 -0
data/lib/mxrb.rb +188 -0
data/marketplace/catalog.json +10 -0
data/marketplace/modules/shared-kernel/domain/README.md +4 -0
data/marketplace/modules/shared-kernel/module.rb +5 -0
data/marketplace/modules/shared-kernel/mxrb-module.json +9 -0
metadata +447 -0

data/lib/mxrb/oql/analyzer.rb ADDED Viewed

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+module Mxrb
+  module Oql
+    # Lightweight positional analysis for OQL and SQL source. This deliberately
+    # stays independent from Translator's tokenizer: findings preserve the
+    # original fragment for editor highlighting.
+    # rubocop:disable Metrics/ClassLength
+    class Analyzer
+      DIALECTS = Translator::DIALECTS
+      LIKE = /\bLIKE\s+'(?<pattern>(?:''|[^'])*)'/i
+      WHERE = /\bWHERE\b(?<body>.*?)(?=\b(?:GROUP\s+BY|ORDER\s+BY|HAVING|LIMIT|OFFSET|UNION)\b|\z)/im
+      FUNCTION = /\b(?:LOWER|UPPER|CAST)\s*\([^)]*\)/i
+      FROM = /\bFROM\b(?<body>.*?)(?=\b(?:WHERE|GROUP\s+BY|ORDER\s+BY|HAVING|LIMIT|OFFSET|UNION)\b|\z)/im
+      SELECT = /\bSELECT\b(?:\s+DISTINCT)?\s+(?<body>.*?)(?=\bFROM\b)/im
+      STAR = %r{(?<!\()(?:\b[A-Za-z_][A-Za-z0-9_$]*\s*/\s*)?\*}
+      def initialize(dialect: :postgresql)
+        @dialect = dialect.to_sym
+        raise ArgumentError, "unsupported analysis dialect #{@dialect.inspect}" \
+          unless DIALECTS.include?(@dialect)
+      end
+      def analyze(query)
+        source = query.oql.to_s
+        findings = [
+          *like_findings(source),
+          *function_findings(source),
+          *cartesian_findings(source),
+          *select_star_findings(source)
+        ].freeze
+        AnalysisReport.new(query, findings)
+      end
+      def analyze_source(source, language: :oql)
+        analyze(ad_hoc_query(source, language))
+      end
+      def analyze_sql(source) = analyze_source(source, language: :sql)
+      private
+      def ad_hoc_query(source, language)
+        kind = language.to_sym
+        raise ArgumentError, "unsupported analysis language #{language.inspect}" \
+          unless %i[oql sql].include?(kind)
+        text = source.to_s.freeze
+        Query.new(
+          'adhoc', 'AdHoc', 'AdHoc', kind, text, nil, [].freeze,
+          kind == :sql ? 'Sql$AdHoc' : 'Oql$AdHoc', Translator.parameters(text)
+        )
+      end
+      def like_findings(source)
+        source.to_enum(:scan, LIKE).filter_map do
+          match = Regexp.last_match
+          classify_like(match[:pattern], match[0])
+        end
+      end
+      def classify_like(pattern, fragment)
+        if pattern.start_with?('%') && pattern.end_with?('%')
+          finding(:like_both_wildcard, :warning, fragment)
+        elsif pattern.start_with?('%')
+          finding(:like_leading_wildcard, :error, fragment)
+        elsif pattern.end_with?('%')
+          finding(:like_trailing_only, :hint, fragment)
+        end
+      end
+      def function_findings(source)
+        source.to_enum(:scan, WHERE).flat_map do
+          body = Regexp.last_match[:body]
+          body.to_enum(:scan, FUNCTION).map do
+            finding(:function_in_where, :warning, Regexp.last_match[0])
+          end
+        end
+      end
+      def cartesian_findings(source)
+        source.to_enum(:scan, FROM).filter_map do
+          match = Regexp.last_match
+          body = match[:body]
+          finding(:cartesian_join, :error, match[0].strip) \
+            if body.include?(',') && !body.match?(/\bJOIN\b/i)
+        end
+      end
+      def select_star_findings(source)
+        source.to_enum(:scan, SELECT).flat_map do
+          body = Regexp.last_match[:body]
+          body.to_enum(:scan, STAR).map do
+            finding(:select_star, :hint, Regexp.last_match[0])
+          end
+        end
+      end
+      def finding(rule, severity, fragment)
+        definition = definitions.fetch(rule)
+        Finding.new(rule, severity, fragment.freeze, definition[:message], definition[:suggestions])
+      end
+      # Keeping messages and dialect alternatives together prevents a rule
+      # from being emitted without an actionable replacement.
+      # rubocop:disable Metrics/MethodLength
+      def definitions
+        @definitions ||= {
+          like_leading_wildcard: definition(
+            'A leading wildcard prevents ordinary index seeks.',
+            postgresql: 'Use pg_trgm with a GIN/GiST index or full-text search.',
+            sql_server: 'Use CONTAINS with a full-text index.',
+            ansi: 'Redesign the predicate or add a dedicated search index.'
+          ),
+          like_both_wildcard: definition(
+            'Wildcards on both sides usually force a full scan.',
+            postgresql: "Use column % 'term' with the pg_trgm extension and an index.",
+            sql_server: "Use CONTAINS(column, 'term') with a full-text index.",
+            ansi: 'Use a search-specific index or redesign the lookup.'
+          ),
+          like_trailing_only: definition(
+            'A trailing-only wildcard can use an index in many configurations.',
+            postgresql: 'Keep the prefix search; confirm operator class, collation, and index use.',
+            sql_server: 'Keep the prefix search; confirm collation and the execution plan.',
+            ansi: 'Keep the prefix search, but verify collation and index behavior.'
+          ),
+          function_in_where: definition(
+            'Applying a function to a filtered column can make the predicate non-sargable.',
+            postgresql: 'Prefer ILIKE where appropriate or create a matching functional index.',
+            sql_server: 'Prefer a case-insensitive collation or an indexed computed column.',
+            ansi: 'Normalize data or compare against a separately indexed normalized column.'
+          ),
+          cartesian_join: definition(
+            'Comma-separated entities without an explicit JOIN risk a Cartesian product.',
+            postgresql: 'Use an explicit JOIN with an ON predicate.',
+            sql_server: 'Use an explicit JOIN with an ON predicate.',
+            ansi: 'Use an explicit JOIN with an ON predicate.'
+          ),
+          select_star: definition(
+            'Selecting every column increases transfer and couples callers to schema changes.',
+            postgresql: 'Project only the columns required by the caller.',
+            sql_server: 'Project only the columns required by the caller.',
+            ansi: 'Project only the columns required by the caller.'
+          )
+        }.freeze
+      end
+      # rubocop:enable Metrics/MethodLength
+      def definition(message, **suggestions)
+        { message: message.freeze, suggestions: suggestions.freeze }.freeze
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/mxrb/oql/index_advisor.rb ADDED Viewed

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+module Mxrb
+  module Oql
+    IndexCandidate = Data.define(:relation, :columns, :confidence, :query_ids, :reason)
+    IndexAdvice = Data.define(:candidates, :redundant_indexes)
+    # Produces hypotheses only when cumulative workload supplies repeatable evidence.
+    class IndexAdvisor
+      TABLE_PATTERN = /\b(?:FROM|JOIN)\s+["\[]?([\w$]+)["\]]?/i
+      PREDICATE_PATTERN = /\b([A-Za-z_]\w*)\s*(?:=|<|>|<=|>=|LIKE|IN\s*\()/i
+      def analyze(report)
+        evidence = collect_evidence(report.queries)
+        candidates = candidates_for(evidence, pressured_relations(report))
+        IndexAdvice.new(candidates.freeze, redundant(report.index_stats).freeze)
+      end
+      private
+      def collect_evidence(queries)
+        evidence = Hash.new { |hash, key| hash[key] = [] }
+        queries.each do |query|
+          relations(query.query).product(predicates(query.query)).each do |relation, column|
+            evidence[[relation.downcase, column.downcase]] << query
+          end
+        end
+        evidence
+      end
+      def pressured_relations(report)
+        report.findings.select { _1.rule == :table_sequential_pressure }
+              .map { _1.subject.to_s.split('.').last.downcase }
+      end
+      def candidates_for(evidence, pressured)
+        evidence.filter_map do |(relation, column), queries|
+          next unless pressured.include?(relation)
+          next unless sufficient_evidence?(queries)
+          IndexCandidate.new(
+            relation, [column].freeze, confidence(queries), queries.map(&:query_id).uniq.freeze,
+            'Repeated filtered workload coincides with cumulative sequential-scan pressure.'
+          )
+        end
+      end
+      def sufficient_evidence?(queries)
+        queries.map(&:query_id).uniq.size >= 2 || queries.sum(&:total_time_ms) >= 1_000
+      end
+      def relations(sql) = sql.to_s.scan(TABLE_PATTERN).flatten.uniq
+      def predicates(sql) = sql.to_s.scan(PREDICATE_PATTERN).flatten.uniq
+      def confidence(queries)
+        return :high if queries.map(&:query_id).uniq.size >= 3 || queries.sum(&:total_time_ms) >= 5_000
+        :medium
+      end
+      def redundant(indexes)
+        indexes.filter_map { index_signature(_1) }.group_by(&:first).values.flat_map do |entries|
+          entries.combination(2).filter_map { redundant_pair(_1, _2) }
+        end
+      end
+      def index_signature(index)
+        columns = index['indexdef'].to_s[/\(([^)]+)\)/, 1]
+        return unless columns
+        [[index['schemaname'], index['relname']], [index['indexrelname'], normalize(columns)]]
+      end
+      def redundant_pair(left, right)
+        left_name, left_columns = left.last
+        right_name, right_columns = right.last
+        [left_name, right_name].freeze if left_columns == right_columns
+      end
+      def normalize(columns)
+        columns.downcase.gsub(/["\[\]\s]/, '')
+      end
+    end
+  end
+end

data/lib/mxrb/oql/plan_analyzer.rb ADDED Viewed

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+module Mxrb
+  module Oql
+    PlanFinding = Data.define(
+      :rule, :severity, :node_type, :relation, :message, :suggestion, :metrics, :indexes
+    )
+    PlanReport = Data.define(
+      :engine, :analyzed, :planning_time_ms, :execution_time_ms, :total_cost, :findings, :raw
+    ) do
+      def clean? = findings.none? { _1.severity == :warning }
+      def warnings? = !clean?
+      def analyzed? = analyzed
+    end
+    # Turns PostgreSQL EXPLAIN JSON into conservative, actionable diagnostics.
+    # A sequential scan is not automatically an error: small-table scans are
+    # often cheaper than an index lookup, so estimates and measured rows decide
+    # whether MXRB emits a hint or a warning.
+    class PlanAnalyzer # rubocop:disable Metrics/ClassLength
+      LARGE_ROWS = 1_000
+      HIGH_COST = 1_000.0
+      MISESTIMATE_RATIO = 10.0
+      METRIC_KEYS = [
+        'Plan Rows', 'Actual Rows', 'Actual Loops', 'Rows Removed by Filter',
+        'Startup Cost', 'Total Cost', 'Actual Total Time', 'Sort Space Used', 'Sort Space Type'
+      ].freeze
+      def initialize(indexes: [])
+        @indexes = Array(indexes).freeze
+      end
+      def analyze(payload, analyzed: false)
+        envelope = Array(payload).first
+        raise ArgumentError, 'invalid PostgreSQL EXPLAIN JSON' unless envelope.is_a?(Hash)
+        root = envelope['Plan']
+        raise ArgumentError, 'PostgreSQL EXPLAIN JSON has no Plan' unless root.is_a?(Hash)
+        findings = walk(root).flat_map { findings_for(_1) }.freeze
+        PlanReport.new(
+          :postgresql, analyzed, envelope['Planning Time'], envelope['Execution Time'],
+          root['Total Cost'], findings, payload
+        )
+      end
+      private
+      def walk(node)
+        [node, *Array(node['Plans']).flat_map { walk(_1) }]
+      end
+      def findings_for(node)
+        [
+          sequential_scan(node), filter_discard(node), cardinality_misestimation(node),
+          nested_loop(node), disk_sort(node)
+        ].compact
+      end
+      def sequential_scan(node)
+        return unless node['Node Type'] == 'Seq Scan'
+        large = relevant_rows(node) >= LARGE_ROWS || number(node['Total Cost']) >= HIGH_COST
+        indexes = indexes_for(node)
+        PlanFinding.new(
+          :sequential_scan, large ? :warning : :hint, 'Seq Scan', qualified_relation(node),
+          scan_message(large), scan_suggestion(node, indexes, large),
+          node_metrics(node).freeze, indexes.freeze
+        )
+      end
+      def scan_message(large)
+        return 'A large sequential scan may dominate this query.' if large
+        'A sequential scan was chosen; it may be optimal for a small relation.'
+      end
+      def filter_discard(node)
+        removed = number(node['Rows Removed by Filter'])
+        return unless removed >= LARGE_ROWS && removed > number(node['Actual Rows'])
+        finding(
+          :filter_discard, node,
+          'The filter discarded more rows than it returned.',
+          'Review predicate selectivity and whether a matching index can filter before heap access.'
+        )
+      end
+      def cardinality_misestimation(node)
+        estimated = number(node['Plan Rows'])
+        actual = number(node['Actual Rows'])
+        return if estimated.zero? || actual.zero?
+        return unless [estimated, actual].max >= 100 && ratio(estimated, actual) >= MISESTIMATE_RATIO
+        finding(
+          :cardinality_misestimation, node,
+          'Estimated and actual row counts differ by at least 10x.',
+          'Run ANALYZE after representative data changes and review extended statistics for correlated columns.'
+        )
+      end
+      def nested_loop(node)
+        return unless node['Node Type'] == 'Nested Loop'
+        rows = relevant_rows(node) * [number(node['Actual Loops']), 1].max
+        return unless rows >= 10_000
+        finding(
+          :high_volume_nested_loop, node,
+          'A nested loop processes a high estimated or measured row volume.',
+          'Check join cardinality and indexes on the inner join keys; compare hash or merge join plans.'
+        )
+      end
+      def disk_sort(node)
+        disk = node['Sort Space Type'] == 'Disk' || node['Sort Method'].to_s.start_with?('external')
+        return unless node['Node Type'] == 'Sort' && disk
+        finding(
+          :disk_sort, node,
+          'The sort spilled to disk.',
+          'Reduce sorted rows, use an order-compatible index, or review work_mem for this workload.'
+        )
+      end
+      def finding(rule, node, message, suggestion)
+        PlanFinding.new(
+          rule, :warning, node['Node Type'], qualified_relation(node), message, suggestion,
+          node_metrics(node).freeze, indexes_for(node).freeze
+        )
+      end
+      def node_metrics(node)
+        METRIC_KEYS.to_h { [_1.downcase.tr(' ', '_').to_sym, node[_1]] }.compact
+      end
+      def relevant_rows(node)
+        [number(node['Plan Rows']), number(node['Actual Rows'])].max
+      end
+      def ratio(left, right)
+        [left, right].max / [left, right].min
+      end
+      def number(value)
+        value ? value.to_f : 0.0
+      end
+      def qualified_relation(node)
+        relation = node['Relation Name']
+        return unless relation
+        schema = node['Schema']
+        schema ? "#{schema}.#{relation}" : relation
+      end
+      def indexes_for(node)
+        relation = node['Relation Name']
+        schema = node['Schema']
+        return [] unless relation
+        @indexes.filter_map do |index|
+          next unless index['tablename'] == relation
+          next if schema && index['schemaname'] != schema
+          { name: index['indexname'], definition: index['indexdef'] }.freeze
+        end
+      end
+      def scan_suggestion(node, indexes, large)
+        return 'No change is implied; compare with an index plan as data grows.' unless large
+        filter = node['Filter']
+        prefix = filter ? "Review the filter #{filter.inspect}. " : 'Review selective predicates. '
+        suffix = if indexes.empty?
+                   'No existing index was found for this relation.'
+                 else
+                   'Compare predicates with the listed existing indexes.'
+                 end
+        prefix + suffix
+      end
+    end # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/mxrb/oql/server.rb ADDED Viewed

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+require 'json'
+require 'webrick'
+module Mxrb
+  module Oql
+    # Loopback-only JSON API for read-only queries against a synchronized
+    # Mendix Runtime database.
+    class Server
+      MAX_BODY_BYTES = 1_048_576
+      attr_reader :host, :port
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(project_path, host: '127.0.0.1', port: 4567, database_port: 55_432,
+                     workspace: nil, logger: nil)
+        @host = host
+        raise ArgumentError, 'the query server must bind to a loopback address' \
+          unless %w[127.0.0.1 ::1 localhost].include?(@host)
+        @port = Integer(port)
+        @workspace = workspace || Runtime::DatabaseWorkspace.new(project_path, port: database_port)
+        @logger = logger || WEBrick::Log.new(File::NULL)
+      end
+      # rubocop:enable Metrics/ParameterLists
+      def start(prepare: true)
+        @workspace.up if prepare
+        @server = WEBrick::HTTPServer.new(
+          BindAddress: @host, Port: @port, Logger: @logger, AccessLog: []
+        )
+        @server.mount_proc('/query') { |request, response| dispatch(request, response) }
+        yield(@server) if block_given?
+        @server.start
+      end
+      def shutdown = @server&.shutdown
+      # rubocop:disable Metrics/MethodLength
+      def execute(payload)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        sql, warnings, params = query_sql(payload)
+        rows = @workspace.query_rows(sql, params:)
+        {
+          ok: true, rows:, row_count: rows.size, elapsed_ms: elapsed_ms(started),
+          warnings:
+        }
+      rescue ArgumentError, JSON::ParserError => e
+        error_payload(e, started, 'invalid_request')
+      rescue StandardError => e
+        error_payload(e, started, 'query_failed')
+      end
+      # rubocop:enable Metrics/MethodLength
+      private
+      # rubocop:disable Metrics/MethodLength
+      def dispatch(request, response)
+        if request.request_method != 'POST'
+          return render(response, 405, ok: false, error: {
+            code: 'method_not_allowed', message: 'use POST /query'
+          })
+        end
+        if request.body.to_s.bytesize > MAX_BODY_BYTES
+          return render(response, 413, ok: false, error: {
+            code: 'request_too_large', message: 'request body exceeds 1 MiB'
+          })
+        end
+        payload = JSON.parse(request.body.to_s)
+        result = execute(payload)
+        render(response, result[:ok] ? 200 : error_status(result), result)
+      rescue JSON::ParserError => e
+        render(response, 400, ok: false, error: {
+          code: 'invalid_json', message: e.message
+        })
+      end
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:disable Metrics/AbcSize
+      def query_sql(payload)
+        raise ArgumentError, 'JSON body must be an object' unless payload.is_a?(Hash)
+        sql = payload['sql']
+        oql = payload['oql']
+        raise ArgumentError, 'provide exactly one of sql or oql' if sql.to_s.empty? == oql.to_s.empty?
+        params = payload.fetch('params', {})
+        raise ArgumentError, 'params must be a JSON object' unless params.is_a?(Hash)
+        return [sql, [], {}] unless sql.to_s.empty?
+        translate_oql(oql, params)
+      end
+      def translate_oql(oql, params)
+        view = Translator.new(dialect: :postgresql).translate_source(oql)
+        raise ArgumentError, view.warnings.join('; ') unless view.supported?
+        expected = view.parameters.map(&:to_s).sort
+        provided = params.keys.map(&:to_s).sort
+        raise ArgumentError, "params must match OQL parameters: #{expected.join(', ')}" \
+          unless provided == expected
+        [view.sql, view.warnings, params]
+      end
+      # rubocop:enable Metrics/AbcSize
+      def elapsed_ms(started)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(3)
+      end
+      def error_payload(error, started, code)
+        {
+          ok: false, error: { code:, message: error.message },
+          elapsed_ms: elapsed_ms(started)
+        }
+      end
+      def error_status(result)
+        result.dig(:error, :code) == 'invalid_request' ? 400 : 422
+      end
+      def render(response, status, payload)
+        response.status = status
+        response['Content-Type'] = 'application/json; charset=utf-8'
+        response.body = JSON.generate(payload)
+      end
+    end
+  end
+end