rails-mmd 0.1.0

data/lib/rails_mmd/generation_pipeline.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/constant_resolver'
+require 'rails_mmd/domain_resolver'
+require 'rails_mmd/diagnostic_factory'
+require 'rails_mmd/ir_builder'
+require 'rails_mmd/mermaid_serializer'
+require 'rails_mmd/model_inventory'
+require 'rails_mmd/relationship_builder'
+require 'rails_mmd/render_plan_builder'
+require 'rails_mmd/redactor'
+require 'rails_mmd/schema_probe'
+
+module RailsMmd
+  # Builds every selected-domain artifact behind one in-process interface.
+  class GenerationPipeline
+    Result = Struct.new(:diagnostics, :artifacts, keyword_init: true)
+
+    def initialize(active_record_base: nil, constant_resolver: ConstantResolver.new, redactor: Redactor.new,
+                   render_plan_builder: nil,
+                   mermaid_serializer: nil)
+      @active_record_base = active_record_base
+      @constant_resolver = ConstantResolver.wrap(constant_resolver)
+      @redactor = redactor
+      @diagnostic_factory = DiagnosticFactory.new(redactor: redactor)
+      @render_plan_builder = render_plan_builder || RenderPlanBuilder.new(redactor: redactor)
+      @mermaid_serializer = mermaid_serializer || MermaidSerializer.new(diagnostics: @diagnostic_factory)
+    end
+
+    def generate(config:)
+      domain_resolution, schema_probe_result, relationship_result, ir_payload = build_stage_results(config)
+      diagnostics = domain_resolution.diagnostics + schema_probe_result.diagnostics + relationship_result.diagnostics
+      artifacts = render_artifacts(config, ir_payload, diagnostics)
+      Result.new(diagnostics: diagnostics, artifacts: artifacts)
+    end
+
+    private
+
+    attr_reader :active_record_base, :constant_resolver, :diagnostic_factory, :mermaid_serializer, :redactor,
+                :render_plan_builder
+
+    def build_stage_results(config)
+      domain_resolution = resolve_domains(config)
+      schema_probe_result = probe_domains(domain_resolution)
+      relationship_result = build_relationships(schema_probe_result)
+      ir_payload = build_ir(config, schema_probe_result, relationship_result)
+      [domain_resolution, schema_probe_result, relationship_result, ir_payload]
+    end
+
+    def resolve_domains(config)
+      inventory = ModelInventory.new(
+        active_record_base: resolved_active_record_base, constant_resolver: constant_resolver, redactor: redactor
+      )
+      DomainResolver.new(diagnostics: diagnostic_factory).resolve(config: config, inventory_records: inventory.records)
+    end
+
+    def probe_domains(domain_resolution)
+      SchemaProbe.new(constant_resolver: constant_resolver, diagnostics: diagnostic_factory, redactor: redactor)
+                 .probe(domains: domain_resolution.domains)
+    end
+
+    def build_relationships(schema_probe_result)
+      RelationshipBuilder.new(constant_resolver: constant_resolver, diagnostics: diagnostic_factory)
+                         .build(domains: schema_probe_result.domains)
+    end
+
+    def build_ir(config, schema_probe_result, relationship_result)
+      IrBuilder.new(attributes: config.output.attributes).build(
+        domains: schema_probe_result.domains, relationship_domains: relationship_result.domains
+      )
+    end
+
+    def render_artifacts(config, ir_payload, diagnostics)
+      ir_payload.domains.to_h do |domain|
+        [domain.domain_id, render_domain_artifacts(config, domain, diagnostics)]
+      end
+    end
+
+    def render_domain_artifacts(config, domain, diagnostics)
+      artifact_kinds(config).each_with_object({}) do |kind, artifacts|
+        render_plan_result = render_plan_for(config, domain, kind, diagnostics)
+        diagnostics.concat(render_plan_result.diagnostics)
+        serialization_result = mermaid_serializer.serialize(render_plan: render_plan_result.payload)
+        diagnostics.concat(serialization_result.diagnostics)
+        next unless serialization_result.diagnostics.empty?
+
+        artifacts[kind] = { render_plan: render_plan_result.payload, mermaid: serialization_result.text }
+      end
+    end
+
+    def render_plan_for(config, domain, kind, diagnostics)
+      render_plan_builder.build(
+        ir: domain.payload,
+        artifact_kind: kind,
+        direction: config.output.direction,
+        attributes: config.output.attributes,
+        available_diagnostic_ids: diagnostics.map { |diagnostic| diagnostic.fetch('diagnostic_id') }
+      )
+    end
+
+    def artifact_kinds(config)
+      config.output.format == 'both' ? %w[er class] : [config.output.format]
+    end
+
+    def resolved_active_record_base
+      active_record_base || Object.const_get(:ActiveRecord).const_get(:Base)
+    end
+  end
+end

data/lib/rails_mmd/ir_builder.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/canonical_json'
+
+module RailsMmd
+  # Normalizes selected schema entities and relationships into closed IR payloads.
+  class IrBuilder
+    DomainResult = Struct.new(:domain_id, :payload, keyword_init: true)
+    Result = Struct.new(:domains, keyword_init: true)
+
+    def initialize(attributes: :keys)
+      @attributes = attributes.to_sym
+    end
+
+    def build(domains:, relationship_domains:)
+      relationships_by_domain = relationship_domains.to_h { |domain| [domain.domain_id, domain] }
+      results = domains.map do |domain|
+        relationship_domain = relationships_by_domain.fetch(domain.domain_id, nil)
+        DomainResult.new(domain_id: domain.domain_id, payload: payload_for(domain, relationship_domain))
+      end
+
+      Result.new(domains: results)
+    end
+
+    private
+
+    attr_reader :attributes
+
+    def payload_for(domain, relationship_domain)
+      payload = payload_without_digest(domain, relationship_domain)
+      payload.merge('digest_sha256' => CanonicalJson.digest_sha256(payload))
+    end
+
+    def payload_without_digest(domain, relationship_domain)
+      {
+        'schema_version' => 1,
+        'domain_id' => domain.domain_id,
+        'entities' => entities_payload(domain, relationship_domain),
+        'relationships' => relationships_payload(relationship_domain),
+        'diagnostic_ids' => diagnostic_ids(domain, relationship_domain),
+        'digest_sha256' => nil
+      }
+    end
+
+    def entities_payload(domain, relationship_domain)
+      payloads = domain.entities.map { |entity| entity_payload(entity, relationship_domain) }
+
+      payloads.sort_by { |entity| entity.fetch('entity_id') }
+    end
+
+    def entity_payload(entity, relationship_domain)
+      {
+        'entity_id' => entity_id(entity),
+        'ruby_constant' => entity.ruby_constant,
+        'table_name' => entity.table_name,
+        'attributes' => attributes_payload(entity, relationship_domain)
+      }
+    end
+
+    def attributes_payload(entity, relationship_domain)
+      return [] if attributes == :none
+
+      names = [[entity.primary_key, 'primary_key']]
+      names.concat(foreign_key_names(entity, relationship_domain).map { |name| [name, 'foreign_key'] })
+      payloads = names.compact.uniq(&:first).map do |name, role|
+        { 'attribute_id' => "#{entity_id(entity)}/attributes/#{name}", 'name' => name, 'role' => role,
+          'type' => column_type(entity, name) }
+      end
+
+      payloads.sort_by do |attribute|
+        [attribute.fetch('role') == 'primary_key' ? 0 : 1, attribute.fetch('attribute_id')]
+      end
+    end
+
+    def foreign_key_names(entity, relationship_domain)
+      return [] unless relationship_domain
+
+      relationship_domain.relationships.flat_map do |relationship|
+        next [] unless relationship.owner_entity_id == entity_id(entity)
+
+        [relationship.foreign_key_column, relationship.foreign_type_column].compact
+      end
+    end
+
+    def column_type(entity, name)
+      entity.columns.find { |column| column.name == name }&.type&.to_s || 'unknown'
+    end
+
+    def relationships_payload(relationship_domain)
+      return [] unless relationship_domain
+
+      payloads = relationship_domain.relationships.map { |relationship| relationship_payload(relationship) }
+
+      payloads.sort_by { |relationship| relationship.fetch('relationship_id') }
+    end
+
+    def relationship_payload(relationship)
+      {
+        'relationship_id' => relationship.relationship_id,
+        'owner_entity_id' => relationship.owner_entity_id,
+        'target_entity_id' => relationship.target_entity_id,
+        'association_name' => relationship.association_name,
+        'owner_cardinality' => relationship.owner_cardinality,
+        'target_cardinality' => relationship.target_cardinality
+      }
+    end
+
+    def diagnostic_ids(domain, relationship_domain)
+      ids = domain.diagnostics.map { |diagnostic| diagnostic.fetch('diagnostic_id') }
+      if relationship_domain
+        ids.concat(relationship_domain.diagnostics.map do |diagnostic|
+          diagnostic.fetch('diagnostic_id')
+        end)
+      end
+      ids.uniq.sort
+    end
+
+    def entity_id(entity)
+      "entities/#{entity.table_name}"
+    end
+  end
+end

data/lib/rails_mmd/mermaid_serializer.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/diagnostic_factory'
+require 'rails_mmd/schema_validator'
+
+module RailsMmd
+  # Serializes renderer-only plans into deterministic P0 Mermaid text.
+  # rubocop:disable-next Metrics/ClassLength
+  class MermaidSerializer
+    Result = Struct.new(:text, :diagnostics, keyword_init: true)
+
+    DOMAIN_ID_PATTERN = /\A[a-z][a-z0-9]*(?:_[a-z0-9]+)*\z/
+    ARTIFACT_KINDS = %w[er class].freeze
+
+    def initialize(diagnostics: DiagnosticFactory.new, schema_validator: SchemaValidator.new)
+      @diagnostic_factory = diagnostics
+      @schema_validator = schema_validator
+    end
+
+    def serialize(render_plan:)
+      schema_validator.validate_render_plan!(render_plan)
+      Result.new(text: text_for(render_plan), diagnostics: [])
+    rescue StandardError => e
+      Result.new(text: nil, diagnostics: [serialization_diagnostic(render_plan, e)])
+    end
+
+    private
+
+    attr_reader :diagnostic_factory, :schema_validator
+
+    def text_for(render_plan)
+      return er_text(render_plan) if render_plan.fetch('artifact_kind') == 'er'
+
+      class_text(render_plan)
+    end
+
+    def er_text(render_plan)
+      lines = header_lines('erDiagram', render_plan) + comment_lines(render_plan)
+      lines.concat(er_body_lines(render_plan))
+      "#{lines.join("\n")}\n"
+    end
+
+    def er_body_lines(render_plan)
+      if render_plan.fetch('entities').any? { |entity| entity.fetch('attributes').any? }
+        return er_relationship_lines(render_plan) +
+               render_plan.fetch('entities').flat_map { |entity| er_entity_lines(entity) }
+      end
+
+      render_plan.fetch('entities').map { |entity| "  #{entity.fetch('safe_token')}" } +
+        er_relationship_lines(render_plan)
+    end
+
+    def class_text(render_plan)
+      lines = header_lines('classDiagram', render_plan) + comment_lines(render_plan)
+      lines.concat(render_plan.fetch('entities').flat_map { |entity| class_entity_lines(entity) })
+      lines.concat(class_relationship_lines(render_plan))
+      "#{lines.join("\n")}\n"
+    end
+
+    def header_lines(diagram, render_plan)
+      [
+        diagram,
+        "  direction #{render_plan.fetch('direction')}"
+      ]
+    end
+
+    def comment_lines(render_plan)
+      render_plan.fetch('comments').map { |comment| "  %% #{line_text(comment.fetch('text'), field: 'comment text')}" }
+    end
+
+    def er_relationship_lines(render_plan)
+      render_plan.fetch('relationships').map do |relationship|
+        "  #{relationship.fetch('owner_safe_token')} #{relationship.fetch('er_left_marker')}.." \
+          "#{relationship.fetch('er_right_marker')} #{relationship.fetch('target_safe_token')} : " \
+          "#{non_empty_label(relationship)}"
+      end
+    end
+
+    def class_relationship_lines(render_plan)
+      render_plan.fetch('relationships').map do |relationship|
+        "  #{relationship.fetch('owner_safe_token')} \"#{relationship.fetch('class_owner_multiplicity')}\" " \
+          "--> \"#{relationship.fetch('class_target_multiplicity')}\" " \
+          "#{relationship.fetch('target_safe_token')} : #{non_empty_label(relationship)}"
+      end
+    end
+
+    def er_entity_lines(entity)
+      return ["  #{entity.fetch('safe_token')}"] if entity.fetch('attributes').empty?
+
+      [
+        "  #{entity.fetch('safe_token')} {",
+        *entity.fetch('attributes').map { |attribute| "    #{er_attribute_line(attribute)}" },
+        '  }'
+      ]
+    end
+
+    def class_entity_lines(entity)
+      return ["  class #{entity.fetch('safe_token')}"] if entity.fetch('attributes').empty?
+
+      [
+        "  class #{entity.fetch('safe_token')} {",
+        *entity.fetch('attributes').map { |attribute| "    #{class_attribute_line(attribute)}" },
+        '  }'
+      ]
+    end
+
+    def er_attribute_line(attribute)
+      [
+        attribute.fetch('type'),
+        line_text(attribute.fetch('label'), field: 'attribute label'),
+        attribute['key_marker']
+      ].compact.join(' ')
+    end
+
+    def class_attribute_line(attribute)
+      "+#{attribute.fetch('type')} #{line_text(attribute.fetch('label'), field: 'attribute label')}"
+    end
+
+    def non_empty_label(relationship)
+      label = line_text(relationship.fetch('label'), field: 'relationship label')
+      raise ArgumentError, 'relationship label is required' if label.empty?
+
+      label
+    end
+
+    def line_text(value, field:)
+      text = value.to_s
+      raise ArgumentError, "#{field} must be single-line" if text.match?(/[\r\n]/)
+
+      text
+    end
+
+    def serialization_diagnostic(render_plan, exception)
+      diagnostic_factory.build(
+        code: 'MERMAID_SERIALIZATION_FAILED',
+        message: 'serialization failed',
+        subject_id: "#{safe_domain_id(render_plan)}:#{safe_artifact_kind(render_plan)}",
+        metadata: serialization_metadata(render_plan, exception)
+      )
+    end
+
+    def serialization_metadata(render_plan, exception)
+      {
+        artifact_kind: safe_artifact_kind(render_plan),
+        domain_id: safe_domain_id(render_plan),
+        reason: exception.message
+      }
+    end
+
+    def safe_artifact_kind(render_plan)
+      return 'er' unless render_plan.is_a?(Hash)
+
+      artifact_kind = render_plan.fetch('artifact_kind', 'er').to_s
+      return artifact_kind if ARTIFACT_KINDS.include?(artifact_kind)
+
+      'er'
+    end
+
+    def safe_domain_id(render_plan)
+      return 'global' unless render_plan.is_a?(Hash)
+
+      domain_id = render_plan.fetch('domain_id', 'global').to_s
+      return domain_id if domain_id.match?(DOMAIN_ID_PATTERN)
+
+      'global'
+    end
+  end
+end

data/lib/rails_mmd/metadata_shapes.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'json_schemer'
+
+module RailsMmd
+  # Reads diagnostic metadata contracts from the diagnostics JSON Schema.
+  class MetadataShapes
+    def initialize(schema_path:)
+      @schema_path = schema_path
+    end
+
+    def fetch(code)
+      shapes.fetch(code)
+    end
+
+    def properties
+      @properties ||= shapes.values.each_with_object({}) do |shape, output|
+        output.merge!(shape.fetch('properties'))
+      end
+    end
+
+    def validate!(code, metadata)
+      errors = schema(code).validate(metadata).to_a
+      return if errors.empty?
+
+      raise ArgumentError, "invalid diagnostic metadata for #{code}: #{errors.first.fetch('data_pointer')}"
+    end
+
+    private
+
+    attr_reader :schema_path
+
+    def shapes
+      @shapes ||= metadata_rules.to_h do |rule|
+        code = rule.dig('if', 'properties', 'code', 'const')
+        ref = rule.dig('then', 'properties', 'metadata', '$ref')
+        [code, definitions.fetch(ref.split('/').last)]
+      end
+    end
+
+    def metadata_rules
+      definitions.values.select { |definition| definition.dig('then', 'properties', 'metadata', '$ref') }
+    end
+
+    def schema(code)
+      @schemas ||= {}
+      @schemas[code] ||= JSONSchemer.schema(fetch(code).merge('$defs' => definitions))
+    end
+
+    def definitions
+      @definitions ||= JSON.parse(schema_path.read).fetch('$defs')
+    end
+  end
+end

data/lib/rails_mmd/model_inventory.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/canonical_json'
+require 'rails_mmd/constant_resolver'
+require 'rails_mmd/redactor'
+
+module RailsMmd
+  # Builds schema-free ActiveRecord model inventory records.
+  # rubocop:disable-next Metrics/ClassLength, Metrics/MethodLength
+  class ModelInventory
+    Record = Struct.new(
+      :ruby_constant,
+      :abstract_class,
+      :base_class,
+      :table_name,
+      :connection_context_id,
+      :renderable,
+      :renderability_reason,
+      keyword_init: true
+    )
+    CONNECTION_CONTEXT_KEYS = %w[name role shard adapter database host port username].freeze
+
+    def initialize(active_record_base:, constant_resolver: ConstantResolver.new,
+                   redactor: Redactor.new)
+      @active_record_base = active_record_base
+      @constant_resolver = ConstantResolver.wrap(constant_resolver)
+      @redactor = redactor
+    end
+
+    def records
+      active_record_base.descendants.filter_map do |model|
+        next unless constant_backed_model?(model)
+
+        build_record(model)
+      end
+    end
+
+    private
+
+    attr_reader :active_record_base, :constant_resolver, :redactor
+
+    def constant_backed_model?(model)
+      model_name = model.name
+      return false unless model_name.is_a?(String) && !model_name.empty?
+
+      constant_resolver.resolve(model_name).equal?(model)
+    end
+
+    def build_record(model)
+      table_name, table_error = table_name_for(model)
+      connection_context_id, connection_context_error = connection_context_id_for(model)
+      abstract = abstract_class?(model)
+      base_model = base_class(model)
+      renderability_reason = renderability_reason(model, abstract, base_model, table_error, connection_context_error)
+
+      Record.new(
+        ruby_constant: model.name,
+        abstract_class: abstract,
+        base_class: base_model&.name,
+        table_name: table_name,
+        connection_context_id: connection_context_id,
+        renderable: renderability_reason.nil?,
+        renderability_reason: renderability_reason
+      )
+    end
+
+    def abstract_class?(model)
+      model.respond_to?(:abstract_class?) && model.abstract_class?
+    end
+
+    def base_class(model)
+      model.respond_to?(:base_class) ? model.base_class : model
+    end
+
+    def table_name_for(model)
+      [model.table_name, nil]
+    rescue StandardError => e
+      [nil, e]
+    end
+
+    def renderability_reason(model, abstract, base_model, table_error, connection_context_error)
+      return 'abstract_class' if abstract
+      return 'sti_subclass' unless base_model.equal?(model)
+      return "table_name_unavailable: #{redactor.sanitize(table_error.message)}" if table_error
+      if connection_context_error
+        return "connection_context_unavailable: #{redactor.sanitize(connection_context_error.message)}"
+      end
+
+      nil
+    end
+
+    def connection_context_id_for(model)
+      [CanonicalJson.dump(connection_context(model)), nil]
+    rescue StandardError => e
+      [CanonicalJson.dump('model' => model.name), e]
+    end
+
+    def connection_context(model)
+      if model.respond_to?(:connection_context)
+        sanitize_context(model.connection_context)
+      elsif model.respond_to?(:connection_db_config)
+        context_from_db_config(model)
+      else
+        { 'model' => model.name }
+      end
+    end
+
+    def context_from_db_config(model)
+      db_config = model.connection_db_config
+      {
+        'name' => connection_context_value(db_config, :name),
+        'role' => connection_context_value(model, :current_role) || 'default',
+        'shard' => connection_context_value(model, :current_shard) || 'default',
+        'adapter' => connection_context_value(db_config, :adapter),
+        'database' => connection_context_value(db_config, :database),
+        'host' => connection_context_value(db_config, :host),
+        'port' => connection_context_value(db_config, :port),
+        'username' => connection_context_value(db_config, :username)
+      }
+    end
+
+    def sanitize_context(context)
+      raw_context = context.to_h.transform_keys(&:to_s)
+      CONNECTION_CONTEXT_KEYS.to_h do |key|
+        [key, sanitize_context_value(raw_context.fetch(key, default_context_value(key)))]
+      end
+    end
+
+    def sanitize_context_value(value)
+      value
+    end
+
+    def default_context_value(key)
+      %w[role shard].include?(key) ? 'default' : nil
+    end
+
+    def connection_context_value(connection_source, method_name)
+      return unless connection_source.respond_to?(method_name)
+
+      context_value = connection_source.public_send(method_name)
+      sanitize_context_value(context_value)
+    end
+  end
+end

data/lib/rails_mmd/ordering.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsMmd
+  # Stable ordering helpers used by later pipeline slices.
+  module Ordering
+    SEVERITY_RANK = { 'fatal' => 0, 'error' => 1, 'warning' => 2 }.freeze
+
+    module_function
+
+    def sort_by_key(records, key)
+      records.sort_by { |record| record.fetch(key) }
+    end
+
+    def sort_diagnostics(records)
+      records.sort_by do |diagnostic|
+        [
+          SEVERITY_RANK.fetch(diagnostic.fetch('severity')),
+          diagnostic.fetch('code'),
+          diagnostic.fetch('subject_id').to_s,
+          diagnostic.fetch('diagnostic_id')
+        ]
+      end
+    end
+  end
+end