rails-mmd 0.1.0

data/lib/rails_mmd/output_directory.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+require 'tmpdir'
+
+module RailsMmd
+  # Validates and resolves project-root-relative output directories.
+  # rubocop:disable-next Metrics/ClassLength
+  class OutputDirectory
+    Resolution = Struct.new(:path, :relative_path, :reason, keyword_init: true) do
+      def valid?
+        reason.nil?
+      end
+    end
+    DRIVE_OR_UNC_PATTERN = /\A(?:[A-Za-z]:|\\\\)/
+    SAFE_RELATIVE_PATH_PATTERN = %r{\A[A-Za-z0-9._/-]+\z}
+    MANAGED_PATH_PATTERN = /
+      \A(?:
+        global\.diagnostics\.json |
+        [a-z][a-z0-9_]*\.(?:diagnostics\.json|(?:er|class)\.mmd|(?:er|class)\.render_plan\.json)
+      )\z
+    /x
+
+    def initialize(project_root:)
+      @project_root = Pathname(project_root).expand_path
+      @project_root_real = @project_root.realpath
+    end
+
+    def resolve(value)
+      text = value.to_s
+      reason = lexical_rejection_reason(text)
+      return invalid_resolution(reason) if reason
+
+      relative_path = normalize(text)
+      return invalid_resolution('normalizes to project root') if relative_path == '.'
+      return invalid_resolution('escapes project root') if relative_path.start_with?('../') || relative_path == '..'
+
+      absolute_path = project_root.join(relative_path)
+      return invalid_resolution('symlink escapes project root') unless inside_project_root?(absolute_path)
+
+      Resolution.new(path: absolute_path, relative_path: relative_path)
+    end
+
+    def publish!(resolution, selected_domain_ids:)
+      raise ArgumentError, 'output directory is unresolved' unless resolution&.valid? && resolution.path
+
+      output_path = resolution.path
+      raise ArgumentError, 'output path escapes project root' unless inside_project_root?(output_path)
+
+      output_path.mkpath
+      ensure_inside_project_root!(output_path)
+      plan = yield
+      ensure_managed_plan!(plan, selected_domain_ids)
+      write_plan(output_path, plan, selected_domain_ids)
+      plan.keys.sort
+    end
+
+    private
+
+    attr_reader :project_root, :project_root_real
+
+    def lexical_rejection_reason(text)
+      return 'is empty' if text.empty?
+      return 'contains NUL' if text.include?("\u0000")
+      return 'contains backslash' if text.include?('\\')
+      return 'uses drive or UNC form' if text.match?(DRIVE_OR_UNC_PATTERN)
+      return 'is absolute' if Pathname(text).absolute?
+
+      'contains unsupported characters' unless text.match?(SAFE_RELATIVE_PATH_PATTERN)
+    end
+
+    def normalize(text)
+      Pathname(text).cleanpath.to_s
+    end
+
+    def inside_project_root?(absolute_path)
+      existing = closest_existing_path(absolute_path)
+      relative = existing.realpath.relative_path_from(project_root_real).to_s
+      relative != '..' && !relative.start_with?('../')
+    rescue Errno::ENOENT
+      false
+    end
+
+    def closest_existing_path(path)
+      current = Pathname(path)
+      current = current.parent until current.exist?
+      current
+    end
+
+    def write_plan(output_path, plan, selected_domain_ids)
+      ensure_safe_replacement_set!(output_path, plan, selected_domain_ids)
+      Dir.mktmpdir('.rails-mmd-', output_path.to_s) do |staging_directory|
+        staging_path = Pathname(staging_directory)
+        plan.each { |relative_path, content| staging_path.join(relative_path).write(content) }
+        ensure_inside_project_root!(output_path)
+        ensure_safe_replacement_set!(output_path, plan, selected_domain_ids)
+        replace_plan_files(output_path, staging_path, plan, selected_domain_ids)
+      end
+    end
+
+    def replace_plan_files(output_path, tmp_path, plan, selected_domain_ids)
+      backup_path = Pathname(Dir.mktmpdir('.rails-mmd-backup-', output_path.to_s))
+      published_paths = []
+      backup_existing_files(output_path, backup_path, selected_domain_ids)
+      move_plan_files(output_path, tmp_path, plan, published_paths)
+      replacement_complete = true
+    rescue StandardError
+      rollback_replacement(output_path, backup_path, published_paths) if backup_path
+      raise
+    ensure
+      FileUtils.remove_entry(backup_path) if backup_path && (replacement_complete || backup_path.children.empty?)
+    end
+
+    def backup_existing_files(output_path, backup_path, selected_domain_ids)
+      scoped_managed_paths(output_path, selected_domain_ids).each do |path|
+        ensure_safe_target!(output_path, path.basename.to_s)
+        FileUtils.mv(path.to_s, backup_path.join(path.basename).to_s)
+      end
+    end
+
+    def move_plan_files(output_path, tmp_path, plan, published_paths)
+      plan.each_key do |relative_path|
+        replace_file(output_path, tmp_path, relative_path)
+        published_paths << relative_path
+      end
+    end
+
+    def rollback_replacement(output_path, backup_path, published_paths)
+      published_paths.each do |relative_path|
+        target = output_path.join(relative_path)
+        target.delete if target.file? && !target.symlink?
+      end
+      backup_path.children.each do |path|
+        ensure_safe_target!(output_path, path.basename.to_s)
+        FileUtils.mv(path.to_s, output_path.join(path.basename).to_s)
+      end
+    end
+
+    def ensure_managed_plan!(plan, selected_domain_ids)
+      plan.each_key do |relative_path|
+        unless relative_path.is_a?(String) && relative_path.match?(MANAGED_PATH_PATTERN) &&
+               scoped_managed_path?(relative_path, selected_domain_ids)
+          raise ArgumentError, 'output plan path is unmanaged'
+        end
+      end
+    end
+
+    def ensure_safe_replacement_set!(output_path, plan, selected_domain_ids)
+      scoped_managed_paths(output_path, selected_domain_ids).each do |path|
+        ensure_safe_target!(output_path, path.basename.to_s)
+      end
+      plan.each_key { |relative_path| ensure_safe_target!(output_path, relative_path) }
+    end
+
+    def scoped_managed_paths(output_path, selected_domain_ids)
+      output_path.children.select do |path|
+        path.basename.to_s.match?(MANAGED_PATH_PATTERN) &&
+          scoped_managed_path?(path.basename.to_s, selected_domain_ids)
+      end
+    end
+
+    def scoped_managed_path?(name, selected_domain_ids)
+      return true if name == 'global.diagnostics.json'
+
+      selected_domain_ids.any? { |domain_id| name.start_with?("#{domain_id}.") }
+    end
+
+    def replace_file(output_path, tmp_path, relative_path)
+      ensure_inside_project_root!(output_path)
+      ensure_safe_target!(output_path, relative_path)
+      FileUtils.mv(tmp_path.join(relative_path).to_s, output_path.join(relative_path).to_s)
+    end
+
+    def ensure_safe_target!(output_path, relative_path)
+      target = output_path.join(relative_path)
+      raise ArgumentError, 'output target is symlink' if target.symlink?
+      raise ArgumentError, 'output target is not a regular file' if target.exist? && !target.file?
+
+      ensure_inside_project_root!(target.parent)
+    end
+
+    def ensure_inside_project_root!(path)
+      relative = path.realpath.relative_path_from(project_root_real).to_s
+      raise ArgumentError, 'output path escapes project root' if relative == '..' || relative.start_with?('../')
+    end
+
+    def invalid_resolution(reason)
+      Resolution.new(reason: reason)
+    end
+  end
+end

data/lib/rails_mmd/publisher.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rails_mmd/diagnostic_factory'
+require 'rails_mmd/output_directory'
+require 'rails_mmd/schema_validator'
+
+module RailsMmd
+  # Atomically publishes diagnostics, render plans, and Mermaid artifacts.
+  # rubocop:disable-next Metrics/ClassLength
+  class Publisher
+    Result = Struct.new(:success, :diagnostics, :written_paths, :stderr, keyword_init: true) do
+      def success?
+        success
+      end
+    end
+
+    PRE_OUTPUT_FATAL_CODES = %w[
+      CONFIG_NOT_FOUND
+      CONFIG_SCHEMA_INVALID
+      CONFIG_DOMAIN_NOT_FOUND
+      OUTPUT_DIRECTORY_INVALID
+    ].freeze
+    ARTIFACT_KINDS = %w[er class].freeze
+    def initialize(project_root:, schema_validator: SchemaValidator.new, diagnostics_factory: DiagnosticFactory.new)
+      @output_directory = OutputDirectory.new(project_root: project_root)
+      @schema_validator = schema_validator
+      @diagnostics_factory = diagnostics_factory
+    end
+
+    def pre_output_stderr(diagnostics)
+      document = schema_validator.validate_pre_output!(diagnostics)
+      "#{JSON.pretty_generate(document)}\n"
+    end
+
+    def publish(output_dir:, selected_domain_ids:, diagnostics:, artifacts:)
+      return pre_output_fatal_result(diagnostics) if pre_output_fatal?(diagnostics)
+
+      output_resolution = output_directory.resolve(output_dir)
+      return invalid_output_result(output_resolution.reason) unless output_resolution.valid?
+
+      publish_inside_output(output_resolution, selected_domain_ids, diagnostics, artifacts)
+    rescue StandardError => e
+      Result.new(success: false, diagnostics: [output_write_failed(e)], written_paths: [], stderr: nil)
+    end
+
+    private
+
+    attr_reader :diagnostics_factory, :output_directory, :schema_validator
+
+    def publish_inside_output(output_resolution, selected_domain_ids, diagnostics, artifacts)
+      written_paths = output_directory.publish!(output_resolution, selected_domain_ids: selected_domain_ids) do
+        diagnostics = scoped_diagnostics(diagnostics, selected_domain_ids)
+        artifacts = scoped_artifacts(artifacts, selected_domain_ids)
+        diagnostic_documents = validate_payloads!(diagnostics, artifacts)
+        blocked_domains = blocked_domains(selected_domain_ids, diagnostics)
+        publish_plan(selected_domain_ids, diagnostic_documents, artifacts, blocked_domains)
+      end
+      Result.new(success: true, diagnostics: diagnostics, written_paths: written_paths, stderr: nil)
+    end
+
+    def validate_payloads!(diagnostics, artifacts)
+      schema_validator.validate_publication!(
+        diagnostics: diagnostics,
+        artifacts: artifacts
+      )
+    end
+
+    def scoped_diagnostics(diagnostics, selected_domain_ids)
+      diagnostics.select do |diagnostic|
+        diagnostic.fetch('scope') == 'invocation' || selected_domain_ids.include?(diagnostic_domain_id(diagnostic))
+      end
+    end
+
+    def scoped_artifacts(artifacts, selected_domain_ids)
+      artifacts.slice(*selected_domain_ids)
+    end
+
+    def publish_plan(selected_domain_ids, diagnostic_documents, artifacts, blocked_domains)
+      plan = diagnostics_plan(diagnostic_documents)
+      selected_domain_ids.each do |domain_id|
+        next if blocked_domains.include?(domain_id)
+
+        plan.merge!(domain_publish_plan(domain_id, artifacts.fetch(domain_id, {})))
+      end
+      plan
+    end
+
+    def domain_publish_plan(domain_id, artifacts)
+      ARTIFACT_KINDS.each_with_object({}) do |kind, plan|
+        artifact = artifacts[kind]
+        next unless artifact
+
+        plan["#{domain_id}.#{kind}.mmd"] = artifact.fetch(:mermaid)
+        plan["#{domain_id}.#{kind}.render_plan.json"] = json_document(artifact.fetch(:render_plan))
+      end
+    end
+
+    def diagnostics_plan(diagnostic_documents)
+      diagnostic_documents.each_with_object({}) do |document, plan|
+        name = if document.fetch('scope') == 'global'
+                 'global.diagnostics.json'
+               else
+                 "#{document.fetch('domain_id')}.diagnostics.json"
+               end
+        plan[name] = json_document(document)
+      end
+    end
+
+    def diagnostic_domain_id(diagnostic)
+      diagnostic.fetch('metadata', {}).fetch('domain_id')
+    end
+
+    def blocked_domains(selected_domain_ids, diagnostics)
+      return selected_domain_ids if invocation_blocking?(diagnostics)
+
+      diagnostics.each_with_object([]) do |diagnostic, blocked|
+        next unless blocking?(diagnostic)
+        next if diagnostic.fetch('scope') == 'invocation'
+
+        blocked << diagnostic_domain_id(diagnostic)
+      end.uniq
+    end
+
+    def invocation_blocking?(diagnostics)
+      diagnostics.any? { |diagnostic| diagnostic.fetch('scope') == 'invocation' && blocking?(diagnostic) }
+    end
+
+    def blocking?(diagnostic)
+      %w[fatal error].include?(diagnostic.fetch('severity'))
+    end
+
+    def json_document(payload)
+      "#{JSON.pretty_generate(payload)}\n"
+    end
+
+    def invalid_output_result(reason)
+      diagnostic = diagnostics_factory.build(
+        code: 'OUTPUT_DIRECTORY_INVALID',
+        message: 'output directory invalid',
+        metadata: { field_path: '$.output.directory', reason: reason.to_s }
+      )
+      Result.new(success: false, diagnostics: [diagnostic], written_paths: [], stderr: pre_output_stderr([diagnostic]))
+    end
+
+    def pre_output_fatal?(diagnostics)
+      diagnostics.any? { |diagnostic| PRE_OUTPUT_FATAL_CODES.include?(diagnostic.fetch('code')) }
+    end
+
+    def pre_output_fatal_result(diagnostics)
+      Result.new(success: false, diagnostics: diagnostics, written_paths: [], stderr: pre_output_stderr(diagnostics))
+    end
+
+    def output_write_failed(exception)
+      diagnostics_factory.build(
+        code: 'OUTPUT_WRITE_FAILED',
+        message: 'output write failed',
+        metadata: { operation: 'write', path: 'output' },
+        remediation: {
+          summary: exception.class.name,
+          steps: ['Check the output directory for retained .rails-mmd-backup-* directories before retrying.']
+        }
+      )
+    end
+  end
+end

data/lib/rails_mmd/rails_loader.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/diagnostic_factory'
+
+module RailsMmd
+  # Boots a host Rails app and eager-loads it through explicit, testable paths.
+  # rubocop:disable-next Metrics/MethodLength
+  class RailsLoader
+    Result = Struct.new(:application, :diagnostics, :exit_code, keyword_init: true) do
+      def success?
+        diagnostics.empty?
+      end
+    end
+
+    EXIT_CONTRACT_ERROR = 2
+
+    def initialize(project_root:, kernel: Kernel, rails_provider: -> { Object.const_get(:Rails) },
+                   diagnostics: DiagnosticFactory.new, bundler: (Bundler if defined?(Bundler)))
+      @project_root = Pathname(project_root).expand_path
+      @kernel = kernel
+      @rails_provider = rails_provider
+      @diagnostic_factory = diagnostics
+      @bundler = bundler
+    end
+
+    def boot
+      validate_bundle_context!
+      kernel.load(environment_path.to_s)
+      application = rails_provider.call.application
+      eager_load(application)
+      Result.new(application: application, diagnostics: [], exit_code: 0)
+    rescue EagerLoadError => e
+      failure('RAILS_EAGER_LOAD_FAILED', e.cause || e)
+    rescue LoadError, SyntaxError, StandardError => e
+      failure('RAILS_LOAD_FAILED', e)
+    end
+
+    private
+
+    class EagerLoadError < StandardError
+    end
+
+    class BundleContextError < StandardError
+    end
+
+    attr_reader :bundler, :diagnostic_factory, :kernel, :project_root, :rails_provider
+
+    def environment_path
+      project_root.join('config/environment.rb')
+    end
+
+    def validate_bundle_context!
+      app_gemfile = project_root.join('Gemfile')
+      return unless app_gemfile.file?
+
+      current_gemfile = current_bundle_gemfile
+      return if current_gemfile &&
+                File.basename(current_gemfile) == app_gemfile.basename.to_s &&
+                File.identical?(File.dirname(current_gemfile), project_root)
+
+      raise BundleContextError,
+            'rails-mmd must be run inside the target Rails application bundle'
+    end
+
+    def current_bundle_gemfile
+      return unless bundler.respond_to?(:default_gemfile)
+
+      bundler.default_gemfile
+    rescue LoadError, StandardError
+      nil
+    end
+
+    def eager_load(application)
+      raise EagerLoadError, 'Rails application does not expose eager_load!' unless application.respond_to?(:eager_load!)
+
+      application.eager_load! if application.respond_to?(:eager_load!)
+    rescue LoadError, SyntaxError, StandardError => e
+      raise EagerLoadError, e.message
+    end
+
+    def failure(code, exception)
+      Result.new(
+        application: nil,
+        diagnostics: [
+          diagnostic_factory.build(
+            code: code,
+            message: exception.message,
+            subject_id: 'rails',
+            metadata: diagnostic_factory.exception_metadata(exception)
+          )
+        ],
+        exit_code: EXIT_CONTRACT_ERROR
+      )
+    end
+  end
+end

data/lib/rails_mmd/redactor.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'uri'
+
+module RailsMmd
+  # Sanitizes free-form text before it can leave the process.
+  # rubocop:disable-next Metrics/ClassLength
+  class Redactor
+    SECRET_KEY_PATTERN = /
+      (?:password|passwd|secret|api[_-]?key|credential|database_url|(?:access|auth|refresh)[_-]?token|\btoken\b)
+    /ix
+    # Free text has no reliable value delimiter, so keep only the context before an assignment.
+    SECRET_ASSIGNMENT_PATTERN = /
+      ["']?[A-Za-z0-9_-]*#{SECRET_KEY_PATTERN}[A-Za-z0-9_-]*["']?\s*(?:=>|=|:)[\s\S]*
+    /ix
+    URL_CREDENTIAL_PATTERN = %r{([a-z][a-z0-9+.-]*://)[^/\s]+@}i
+    DRIVE_OR_UNC_PATTERN = %r{\b(?:[A-Za-z]:[\\/]|\\\\[^\\/\s]+[\\/][^\\/\s]+)}
+    MERMAID_SECRET_KEY = /
+      (?:
+        password|passwd|secret|credential|token|pid|
+        api\s*[_-]?\s*key|
+        database\s*[_-]?\s*url|
+        (?:access|auth|refresh)\s*[_-]?\s*token|
+        generated\s*[_-]?\s*at|
+        process\s*[_-]?\s*id|
+        random\s*[_-]?\s*seed|
+        raw\s*[_-]?\s*exception\s*[_-]?\s*backtrace
+      )
+    /ix
+    MERMAID_FORBIDDEN_ASSIGNMENT = /
+      ["']?[A-Za-z0-9_-]*#{MERMAID_SECRET_KEY}[A-Za-z0-9_-]*["']?\s*(?:=>|:|=|\s+)[\s\S]*
+    /ix
+    REDACTED_KEY_ASSIGNMENT = /
+      ["']?[A-Za-z0-9_-]*\[REDACTED_KEY\][A-Za-z0-9_-]*["']?\s*(?:=>|:|=|\s+)[\s\S]*
+    /x
+    URL_PATTERN = %r{\b[a-z][a-z0-9+.-]*://[^\s]+}i
+    URL_PLACEHOLDER_PREFIX = "\uE000RAILSMMDURL"
+    REDACTED_URL = '[REDACTED_URL]'
+    MERMAID_CONTROL_TEXT = /[\r\n\t[:cntrl:]]+/
+    CONTROL_SPLIT_ABSOLUTE_PATH =
+      /(?<![A-Za-z0-9_])\/[^[:cntrl:]\s)\]}>;,:!?]+(?:[\r\n\t[:cntrl:]][^[:cntrl:]\s)\]}>;,:!?]*)*/
+    STRUCTURED_PATTERNS = {
+      ruby_constant: /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/,
+      ruby_constant_label: /\A[A-Z][A-Za-z0-9_]*\z/,
+      snake_identifier: /\A[a-z][a-z0-9_]*\z/
+    }.freeze
+    STRUCTURED_FALLBACK = 'X'
+
+    class << self
+      def sanitize_mermaid_free_text(value, sanitizer:)
+        urls = []
+        text = protect_urls(value.to_s.delete("\u0000"), urls)
+        text = text.gsub(CONTROL_SPLIT_ABSOLUTE_PATH, '[REDACTED_PATH]')
+        text = text.gsub(MERMAID_CONTROL_TEXT, ' ')
+        text = text.gsub(MERMAID_FORBIDDEN_ASSIGNMENT, '[REDACTED]')
+        text = sanitizer.sanitize(text).gsub(REDACTED_KEY_ASSIGNMENT, '[REDACTED]')
+        restore_urls(text, urls).gsub(/\s+/, ' ').strip
+      end
+
+      def sanitize_mermaid_structured(value, grammar:)
+        text = value.to_s.delete("\u0000").gsub(MERMAID_CONTROL_TEXT, ' ').gsub(/\s+/, ' ').strip
+        return STRUCTURED_FALLBACK unless STRUCTURED_PATTERNS.fetch(grammar).match?(text)
+
+        text
+      end
+
+      private
+
+      def protect_urls(text, urls)
+        text.gsub(URL_PATTERN) do |_url|
+          urls << REDACTED_URL
+          "#{URL_PLACEHOLDER_PREFIX}#{urls.length - 1}"
+        end
+      end
+
+      def restore_urls(text, urls)
+        urls.each_with_index.reduce(text) do |output, (url, index)|
+          output.gsub("#{URL_PLACEHOLDER_PREFIX}#{index}", url)
+        end
+      end
+    end
+
+    def initialize(project_root: Dir.pwd, env: ENV.to_h)
+      @project_root = Pathname(project_root).expand_path
+      @env_values = env.values.compact.map(&:to_s).select { |value| value.length >= 4 }.uniq
+    end
+
+    def sanitize(value)
+      text = value.to_s.dup
+      text = text.delete("\u0000")
+      text = text.gsub(URL_CREDENTIAL_PATTERN, '\\1[REDACTED]@')
+      text = text.gsub(SECRET_ASSIGNMENT_PATTERN, '[REDACTED]')
+      text = text.gsub(DRIVE_OR_UNC_PATTERN, '[REDACTED_PATH]')
+      text = redact_absolute_paths(text)
+      text = redact_env_values(text)
+      text.gsub(SECRET_KEY_PATTERN, '[REDACTED_KEY]')
+    end
+
+    def sanitize_object(value)
+      case value
+      when String
+        sanitize(value)
+      when Array
+        value.map { |item| sanitize_object(item) }
+      when Hash
+        sanitize_hash(value)
+      else
+        value
+      end
+    end
+
+    private
+
+    attr_reader :project_root, :env_values
+
+    def sanitize_hash(value)
+      value.to_h do |key, item|
+        sanitized_value = SECRET_KEY_PATTERN.match?(key.to_s) ? '[REDACTED]' : sanitize_object(item)
+        [sanitize(key), sanitized_value]
+      end
+    end
+
+    def redact_env_values(text)
+      env_values.reduce(text) { |output, value| output.gsub(value, '[REDACTED]') }
+    end
+
+    def redact_absolute_paths(text)
+      text.gsub(%r{(?:/[\w.-]+){2,}}) do |path|
+        display_path(path)
+      end
+    end
+
+    def display_path(path)
+      pathname = Pathname(path)
+      expanded = pathname.expand_path
+      relative = expanded.relative_path_from(project_root)
+      return relative.to_s unless relative.to_s.start_with?('..')
+
+      '[REDACTED_PATH]'
+    end
+  end
+end