rails-mmd 0.1.0

data/lib/rails_mmd/config.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'rails_mmd/diagnostic_factory'
+require 'rails_mmd/output_directory'
+require 'rails_mmd/redactor'
+require 'rails_mmd/schema_validator'
+
+module RailsMmd
+  # Loads and resolves the P0 YAML configuration contract without exposing CLI routing.
+  # rubocop:disable-next Metrics/ClassLength, Metrics/AbcSize, Metrics/MethodLength
+  class Config
+    DEFAULT_CONFIG_PATH = 'rails_mmd.yml'
+    DEFAULT_OUTPUT = {
+      'directory' => 'docs/rails_mmd',
+      'format' => 'both',
+      'attributes' => 'keys',
+      'direction' => 'LR'
+    }.freeze
+    DOMAIN_ID_PATTERN = /\A[a-z][a-z0-9]*(?:_[a-z0-9]+)*\z/
+    VALID_FORMATS = %w[er class both].freeze
+    EXIT_CONTRACT_ERROR = 2
+
+    CliOptions = Struct.new(:config_path, :output_dir, :domain, :format, keyword_init: true)
+    Domain = Struct.new(:domain_id, :include_models, :exclude_models, keyword_init: true)
+    Output = Struct.new(:directory, :path, :format, :attributes, :direction, :sources, keyword_init: true)
+    Resolved = Struct.new(:config_path, :domains, :output, :selected_domain_ids, keyword_init: true)
+    Result = Struct.new(:config, :diagnostics, :exit_code, keyword_init: true) do
+      def success?
+        diagnostics.empty?
+      end
+    end
+
+    def initialize(project_root: Dir.pwd, validator: SchemaValidator.new, redactor: nil)
+      @project_root = Pathname(project_root).expand_path
+      @validator = validator
+      @redactor = redactor || Redactor.new(project_root: @project_root)
+      @diagnostic_factory = DiagnosticFactory.new(redactor: @redactor)
+      @output_directory = OutputDirectory.new(project_root: @project_root)
+    end
+
+    def load(cli_options: CliOptions.new)
+      config_path = resolve_config_path(cli_options.config_path)
+      return failure(config_not_found(config_path)) unless config_path.file?
+
+      data = safe_load(config_path)
+      return failure(config_schema_invalid(config_path, 'config', 'must be a YAML mapping')) unless data.is_a?(Hash)
+
+      output_directory_error = configured_output_directory_error(data, cli_options)
+      return failure(output_directory_error) if output_directory_error
+
+      schema_errors = validator.errors(:config, data_for_schema_validation(data, cli_options))
+      unless schema_errors.empty?
+        return failure(config_schema_invalid(config_path, field_path(schema_errors.first),
+                                             'does not match config schema'))
+      end
+
+      build_config(config_path, data, cli_options)
+    rescue Psych::Exception => e
+      failure(config_schema_invalid(config_path, 'config', e.message))
+    end
+
+    private
+
+    attr_reader :diagnostic_factory, :output_directory, :project_root, :validator
+
+    def build_config(config_path, data, cli_options)
+      domains = build_domains(data.fetch('domains'))
+      output = build_output(data.fetch('output', {}), cli_options)
+      unless output.fetch(:directory_result).valid?
+        return failure(output_directory_invalid(output.fetch(:directory_result),
+                                                output.fetch(:directory_source)))
+      end
+      unless VALID_FORMATS.include?(output.fetch(:format))
+        return failure(config_schema_invalid(config_path, '$.cli.format',
+                                             'must be er, class, or both'))
+      end
+
+      unless valid_domain_selection?(cli_options.domain)
+        return failure(config_schema_invalid(config_path, '$.cli.domain',
+                                             'must match domain ID grammar'))
+      end
+
+      selected_domain_ids = selected_domain_ids(domains, cli_options.domain)
+      if selected_domain_ids.nil?
+        return failure(diagnostic_factory.build(
+                         code: 'CONFIG_DOMAIN_NOT_FOUND',
+                         message: "Unknown domain #{cli_options.domain}",
+                         subject_id: "domain:#{cli_options.domain}",
+                         metadata: { domain_id: cli_options.domain.to_s }
+                       ))
+      end
+
+      success(config_path, domains, output, selected_domain_ids)
+    end
+
+    def build_domains(domain_data)
+      domain_data.to_h do |domain_id, domain|
+        [
+          domain_id,
+          Domain.new(
+            domain_id: domain_id,
+            include_models: domain.fetch('include_models'),
+            exclude_models: domain.fetch('exclude_models', [])
+          )
+        ]
+      end
+    end
+
+    def build_output(data, cli_options)
+      directory_source = cli_options.output_dir.nil? ? '$.output.directory' : '$.cli.output_dir'
+      directory = cli_options.output_dir || data.fetch('directory', DEFAULT_OUTPUT.fetch('directory'))
+      format = cli_options.format || data.fetch('format', DEFAULT_OUTPUT.fetch('format'))
+
+      {
+        directory_result: output_directory.resolve(directory),
+        directory_source: directory_source,
+        format: format,
+        attributes: data.fetch('attributes', DEFAULT_OUTPUT.fetch('attributes')),
+        direction: data.fetch('direction', DEFAULT_OUTPUT.fetch('direction')),
+        sources: {
+          'directory' => source_for(cli_options.output_dir, data, 'directory'),
+          'format' => source_for(cli_options.format, data, 'format'),
+          'attributes' => data.key?('attributes') ? 'config' : 'default',
+          'direction' => data.key?('direction') ? 'config' : 'default'
+        }
+      }
+    end
+
+    def selected_domain_ids(domains, selected_domain)
+      return domains.keys if selected_domain.nil?
+      return [selected_domain] if domains.key?(selected_domain)
+
+      nil
+    end
+
+    def success(config_path, domains, output_data, selected_domain_ids)
+      directory = output_data.fetch(:directory_result)
+      output = Output.new(
+        directory: directory.relative_path,
+        path: directory.path,
+        format: output_data.fetch(:format),
+        attributes: output_data.fetch(:attributes),
+        direction: output_data.fetch(:direction),
+        sources: output_data.fetch(:sources)
+      )
+      config = Resolved.new(config_path: config_path, domains: domains, output: output,
+                            selected_domain_ids: selected_domain_ids)
+
+      Result.new(config: config, diagnostics: [], exit_code: 0)
+    end
+
+    def failure(diagnostic)
+      Result.new(config: nil, diagnostics: [diagnostic], exit_code: EXIT_CONTRACT_ERROR)
+    end
+
+    def config_not_found(config_path)
+      diagnostic_factory.build(
+        code: 'CONFIG_NOT_FOUND',
+        message: "Config file not found: #{display_path(config_path)}",
+        subject_id: 'config',
+        metadata: { config_path: display_path(config_path) }
+      )
+    end
+
+    def config_schema_invalid(config_path, field_path_value, reason)
+      diagnostic_factory.build(
+        code: 'CONFIG_SCHEMA_INVALID',
+        message: "Invalid config #{display_path(config_path)}: #{reason}",
+        subject_id: 'config',
+        metadata: { config_path: display_path(config_path), field_path: field_path_value }
+      )
+    end
+
+    def output_directory_invalid(result, field_path_value)
+      diagnostic_factory.build(
+        code: 'OUTPUT_DIRECTORY_INVALID',
+        message: "Invalid output directory: #{result.reason}",
+        subject_id: 'output.directory',
+        metadata: { field_path: field_path_value, reason: result.reason }
+      )
+    end
+
+    def data_for_schema_validation(data, cli_options)
+      data = deep_dup(data)
+      output = data['output']
+      return data unless output.is_a?(Hash)
+
+      output.delete('directory') unless cli_options.output_dir.nil?
+      output.delete('format') unless cli_options.format.nil?
+      data
+    end
+
+    def configured_output_directory_error(data, cli_options)
+      return if cli_options.output_dir
+
+      output = data['output']
+      return unless output.is_a?(Hash) && output.key?('directory') && output.fetch('directory').is_a?(String)
+
+      result = output_directory.resolve(output.fetch('directory'))
+      output_directory_invalid(result, '$.output.directory') unless result.valid?
+    end
+
+    def resolve_config_path(value)
+      Pathname(value || DEFAULT_CONFIG_PATH).then do |path|
+        path.absolute? ? path : project_root.join(path)
+      end
+    end
+
+    def display_path(path)
+      relative = Pathname(path).expand_path.relative_path_from(project_root).to_s
+      return relative unless relative.start_with?('..')
+
+      DEFAULT_CONFIG_PATH
+    end
+
+    def safe_load(path)
+      YAML.safe_load(path.read, permitted_classes: [], permitted_symbols: [], aliases: false)
+    end
+
+    def field_path(error)
+      pointer = error&.fetch('data_pointer', nil).to_s
+      return '$' if pointer.empty?
+
+      "$.#{pointer.delete_prefix('/').tr('/', '.')}"
+    end
+
+    def source_for(cli_value, config_data, key)
+      return 'cli' unless cli_value.nil?
+
+      config_data.key?(key) ? 'config' : 'default'
+    end
+
+    def valid_domain_selection?(domain)
+      domain.nil? || domain.match?(DOMAIN_ID_PATTERN)
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash
+        value.transform_values { |item| deep_dup(item) }
+      when Array
+        value.map { |item| deep_dup(item) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/rails_mmd/constant_resolver.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RailsMmd
+  # Resolves exact Ruby constants while containing ordinary autoload failures.
+  # @api private
+  class ConstantResolver
+    def self.wrap(resolver)
+      return resolver if resolver.is_a?(self)
+      return new(loader: resolver.method(:resolve)) if resolver.respond_to?(:resolve)
+      return new(loader: resolver) if resolver.respond_to?(:call)
+
+      raise ArgumentError, 'constant resolver must respond to resolve or call'
+    end
+
+    def initialize(loader: method(:load_constant))
+      @loader = loader
+    end
+
+    def resolve(name)
+      loader.call(name)
+    rescue ScriptError, StandardError
+      nil
+    end
+
+    private
+
+    attr_reader :loader
+
+    def load_constant(name)
+      name.split('::').reduce(Object) { |namespace, const_name| namespace.const_get(const_name, false) }
+    end
+  end
+end

data/lib/rails_mmd/diagnostic_factory.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rails_mmd/artifact_ref_sanitizer'
+require 'rails_mmd/canonical_json'
+require 'rails_mmd/metadata_shapes'
+require 'rails_mmd/redactor'
+require 'rails_mmd/subject_ids'
+
+module RailsMmd
+  # Schema-backed diagnostic object factory.
+  class DiagnosticFactory
+    CATALOG_PATH = Pathname(__dir__).join('../../fixtures/schemas/diagnostics/valid/catalog.json').expand_path
+    SCHEMA_PATH = Pathname(__dir__).join('../../schemas/diagnostics.schema.json').expand_path
+    FREE_TEXT_REFS = %w[#/$defs/relative_path #/$defs/sanitized_string].freeze
+
+    def initialize(redactor: Redactor.new, artifact_refs: ArtifactRefSanitizer.new(redactor: redactor))
+      @redactor = redactor
+      @artifact_refs = artifact_refs
+    end
+
+    def build(code:, message:, **options)
+      template = self.class.catalog.fetch(code)
+      diagnostic = diagnostic_payload(code, message, template, options)
+      validate_metadata_keys!(code, diagnostic.fetch('metadata'))
+      self.class.metadata_shapes.validate!(code, diagnostic.fetch('metadata'))
+      diagnostic
+    end
+
+    def diagnostic_payload(code, message, template, options)
+      metadata = options.fetch(:metadata, {})
+      content = diagnostic_content(code, message, options, metadata)
+      diagnostic_defaults(code, template, options, content).merge(content)
+    end
+
+    def diagnostic_defaults(code, template, options, content)
+      {
+        'diagnostic_id' => diagnostic_id(code, content.fetch('subject_id'), content.fetch('metadata')),
+        'code' => code,
+        'severity' => options[:severity] || template.fetch('severity'),
+        'phase' => template.fetch('phase'),
+        'scope' => template.fetch('scope')
+      }
+    end
+
+    def diagnostic_content(code, message, options, metadata)
+      {
+        'subject_id' => SubjectIds.normalize(options[:subject_id], code: code),
+        'message' => redactor.sanitize(message),
+        'metadata' => sanitized_metadata(code, metadata),
+        'artifact_refs' => artifact_refs.sanitize(options.fetch(:artifact_refs, [])),
+        'remediation' => options[:remediation] && redactor.sanitize_object(options[:remediation])
+      }
+    end
+
+    def exception_metadata(exception)
+      {
+        'exception_class' => exception.class.name,
+        'exception_summary' => redactor.sanitize(exception.message),
+        'backtrace' => nil
+      }
+    end
+
+    def self.codes
+      catalog.keys
+    end
+
+    def self.catalog
+      @catalog ||= JSON.parse(CATALOG_PATH.read).fetch('diagnostics').to_h do |diagnostic|
+        [diagnostic.fetch('code'), diagnostic]
+      end
+    end
+
+    def self.metadata_shapes
+      @metadata_shapes ||= MetadataShapes.new(schema_path: SCHEMA_PATH)
+    end
+
+    private
+
+    attr_reader :artifact_refs, :redactor
+
+    def diagnostic_id(code, subject_id, metadata)
+      digest = CanonicalJson.digest_sha256('code' => code, 'subject_id' => subject_id, 'metadata' => metadata)
+      "diag_#{digest[0, 16]}"
+    end
+
+    def sanitized_metadata(code, metadata)
+      shape = self.class.metadata_shapes.fetch(code)
+      template_keys = shape.fetch('properties').keys
+      metadata = stringify_keys(metadata)
+      raise ArgumentError, "unknown diagnostic metadata for #{code}" unless (metadata.keys - template_keys).empty?
+
+      metadata.transform_values.with_index do |value, index|
+        sanitize_metadata_value(metadata.keys.fetch(index), value)
+      end
+    end
+
+    def sanitize_metadata_value(key, value)
+      return value unless metadata_free_text?(key)
+      raise ArgumentError, "invalid diagnostic metadata value for #{key}" unless value.is_a?(String)
+
+      redactor.sanitize(value)
+    end
+
+    def metadata_free_text?(key)
+      FREE_TEXT_REFS.include?(self.class.metadata_shapes.properties.fetch(key).fetch('$ref', nil))
+    end
+
+    def validate_metadata_keys!(code, metadata)
+      required_keys = self.class.metadata_shapes.fetch(code).fetch('required')
+      missing_keys = required_keys - metadata.keys
+      return if missing_keys.empty?
+
+      raise ArgumentError,
+            "missing diagnostic metadata for #{code}: #{missing_keys.join(', ')}"
+    end
+
+    def stringify_keys(value)
+      value.to_h.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/rails_mmd/domain_resolver.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/diagnostic_factory'
+
+module RailsMmd
+  # Resolves configured domains exactly against schema-free inventory records.
+  class DomainResolver
+    DomainResult = Struct.new(:domain_id, :records, :diagnostics, keyword_init: true)
+    Result = Struct.new(:domains, :diagnostics, keyword_init: true)
+
+    def initialize(diagnostics: DiagnosticFactory.new)
+      @diagnostic_factory = diagnostics
+    end
+
+    def resolve(config:, inventory_records:)
+      records_by_constant = inventory_records.to_h { |record| [record.ruby_constant, record] }
+      domain_results = config.selected_domain_ids.map do |domain_id|
+        resolve_domain(config.domains.fetch(domain_id), records_by_constant)
+      end
+      all_diagnostics = domain_results.flat_map(&:diagnostics)
+
+      Result.new(domains: domain_results, diagnostics: all_diagnostics)
+    end
+
+    private
+
+    attr_reader :diagnostic_factory
+
+    def resolve_domain(domain, records_by_constant)
+      include_records, include_diagnostics = resolve_model_list(domain, domain.include_models, records_by_constant)
+      exclude_records, exclude_diagnostics = resolve_model_list(domain, domain.exclude_models, records_by_constant)
+      selected_records = selected_records(include_records, exclude_records)
+      empty_diagnostic = selected_records.empty? ? [domain_empty(domain.domain_id)] : []
+
+      DomainResult.new(
+        domain_id: domain.domain_id,
+        records: selected_records,
+        diagnostics: include_diagnostics + exclude_diagnostics + empty_diagnostic
+      )
+    end
+
+    def selected_records(include_records, exclude_records)
+      excluded = exclude_records.to_set(&:ruby_constant)
+      seen = Set.new
+      include_records.each_with_object([]) do |record, selected|
+        next if excluded.include?(record.ruby_constant) || seen.include?(record.ruby_constant)
+
+        seen << record.ruby_constant
+        selected << record
+      end
+    end
+
+    def resolve_model_list(domain, ruby_constants, records_by_constant)
+      ruby_constants.each_with_object([[], []]) do |ruby_constant, (records, output_diagnostics)|
+        record = records_by_constant[ruby_constant]
+        if record.nil?
+          output_diagnostics << model_not_found(domain.domain_id, ruby_constant)
+        elsif record.renderable
+          records << record
+        else
+          output_diagnostics << model_not_renderable(domain.domain_id, record)
+        end
+      end
+    end
+
+    def model_not_found(domain_id, ruby_constant)
+      diagnostic_factory.build(
+        code: 'DOMAIN_MODEL_NOT_FOUND',
+        message: "Domain #{domain_id} references missing model #{ruby_constant}",
+        subject_id: "#{domain_id}:#{ruby_constant}",
+        metadata: { domain_id: domain_id, ruby_constant: ruby_constant }
+      )
+    end
+
+    def model_not_renderable(domain_id, record)
+      diagnostic_factory.build(
+        code: 'DOMAIN_MODEL_NOT_RENDERABLE',
+        message: "Domain #{domain_id} references non-renderable model #{record.ruby_constant}",
+        subject_id: "#{domain_id}:#{record.ruby_constant}",
+        metadata: {
+          domain_id: domain_id,
+          ruby_constant: record.ruby_constant,
+          renderability_reason: record.renderability_reason
+        }
+      )
+    end
+
+    def domain_empty(domain_id)
+      diagnostic_factory.build(
+        code: 'DOMAIN_EMPTY',
+        message: "Domain #{domain_id} has no renderable models",
+        subject_id: domain_id,
+        metadata: { domain_id: domain_id }
+      )
+    end
+  end
+end

data/lib/rails_mmd/exit_policy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RailsMmd
+  # Maps diagnostics to the public P0 process exit contract.
+  module ExitPolicy
+    EXIT_CODE_BY_DIAGNOSTIC_CODE = {
+      'MERMAID_SERIALIZATION_FAILED' => 3,
+      'SAFE_TOKEN_COLLISION' => 3,
+      'OUTPUT_WRITE_FAILED' => 4,
+      'INTERNAL_ERROR' => 99
+    }.freeze
+    BLOCKING_SEVERITIES = %w[fatal error].freeze
+
+    module_function
+
+    def exit_code(diagnostics, fail_on_warning: false)
+      blocking = diagnostics.select { |diagnostic| BLOCKING_SEVERITIES.include?(diagnostic.fetch('severity')) }
+      if blocking.empty?
+        return 1 if fail_on_warning && diagnostics.any? { |diagnostic| diagnostic.fetch('severity') == 'warning' }
+
+        return 0
+      end
+
+      blocking.map { |diagnostic| EXIT_CODE_BY_DIAGNOSTIC_CODE.fetch(diagnostic.fetch('code'), 2) }.max
+    end
+  end
+end

data/lib/rails_mmd/generate_command.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/config'
+require 'rails_mmd/exit_policy'
+require 'rails_mmd/generation_pipeline'
+require 'rails_mmd/publisher'
+require 'rails_mmd/rails_loader'
+require 'rails_mmd/redactor'
+
+module RailsMmd
+  # Coordinates the P0 generate pipeline behind the Thor command.
+  # @api private
+  class GenerateCommand
+    Result = Struct.new(:exit_code, :stdout, :stderr, :diagnostics, keyword_init: true) do
+      def success?
+        exit_code.zero?
+      end
+    end
+
+    def initialize(project_root: Dir.pwd, rails_loader: nil, pipeline: nil)
+      @project_root = Pathname(project_root).expand_path
+      @rails_loader = rails_loader
+      @pipeline = pipeline
+    end
+
+    def run(cli_options:, fail_on_warning: false)
+      config_result = Config.new(project_root: project_root, redactor: redactor).load(cli_options: cli_options)
+      return pre_output_result(config_result.diagnostics, config_result.exit_code) unless config_result.success?
+
+      run_pipeline(config_result.config, fail_on_warning)
+    rescue StandardError => e
+      internal_error_result(e)
+    end
+
+    private
+
+    attr_reader :project_root
+
+    def run_pipeline(config, fail_on_warning)
+      rails_result = rails_loader.boot
+      return pre_output_result(rails_result.diagnostics, rails_result.exit_code) unless rails_result.success?
+
+      pipeline_result = generate_artifacts(config)
+      publish_result(config, pipeline_result.diagnostics, pipeline_result.artifacts, fail_on_warning)
+    end
+
+    def publish_result(config, diagnostics, artifacts, fail_on_warning)
+      publication_result = publisher.publish(
+        output_dir: config.output.directory,
+        selected_domain_ids: config.selected_domain_ids,
+        diagnostics: diagnostics,
+        artifacts: artifacts
+      )
+      command_result_for(publication_result, fail_on_warning)
+    end
+
+    def command_result_for(publication_result, fail_on_warning)
+      Result.new(
+        exit_code: publication_exit_code(publication_result, fail_on_warning),
+        stdout: '',
+        stderr: publication_stderr(publication_result),
+        diagnostics: publication_result.diagnostics
+      )
+    end
+
+    def publication_exit_code(publication_result, fail_on_warning)
+      ExitPolicy.exit_code(publication_result.diagnostics, fail_on_warning: fail_on_warning)
+    end
+
+    def publication_stderr(publication_result)
+      return publication_result.stderr.to_s unless publication_result.stderr.to_s.empty?
+      return '' if publication_result.success?
+
+      publisher.pre_output_stderr(publication_result.diagnostics)
+    end
+
+    def pre_output_result(diagnostics, exit_code)
+      Result.new(exit_code: exit_code, stdout: '', stderr: publisher.pre_output_stderr(diagnostics),
+                 diagnostics: diagnostics)
+    end
+
+    def internal_error_result(exception)
+      diagnostic = diagnostics_factory.build(
+        code: 'INTERNAL_ERROR',
+        message: 'internal error',
+        metadata: diagnostics_factory.exception_metadata(exception)
+      )
+      Result.new(exit_code: 99, stdout: '', stderr: publisher.pre_output_stderr([diagnostic]),
+                 diagnostics: [diagnostic])
+    end
+
+    def rails_loader
+      @rails_loader ||= RailsLoader.new(project_root: project_root, diagnostics: diagnostics_factory)
+    end
+
+    def publisher
+      @publisher ||= Publisher.new(project_root: project_root, diagnostics_factory: diagnostics_factory)
+    end
+
+    def diagnostics_factory
+      @diagnostics_factory ||= DiagnosticFactory.new(redactor: redactor)
+    end
+
+    def redactor
+      @redactor ||= Redactor.new(project_root: project_root)
+    end
+
+    def pipeline
+      @pipeline ||= GenerationPipeline.new(redactor: redactor)
+    end
+
+    def generate_artifacts(config)
+      pipeline.generate(config: config)
+    end
+  end
+end