rails-mmd 0.1.0

data/lib/rails_mmd/schema_validator.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'json_schemer'
+require 'rails_mmd/canonical_json'
+require 'rails_mmd/ordering'
+
+module RailsMmd
+  # Validates payloads against repository JSON Schemas.
+  class SchemaValidator
+    class InvalidPayload < ArgumentError; end
+
+    SCHEMA_FILES = {
+      config: 'config.schema.json',
+      diagnostics: 'diagnostics.schema.json',
+      ir: 'ir.schema.json',
+      render_plan: 'render_plan.schema.json'
+    }.freeze
+
+    def initialize(schema_root: Pathname(__dir__).join('../../schemas').expand_path)
+      @schema_root = Pathname(schema_root)
+      @schemas = {}
+    end
+
+    def valid?(schema_name, payload) = errors(schema_name, payload).empty?
+
+    def errors(schema_name, payload)
+      schema(schema_name).validate(payload).to_a + attribute_identity_errors(schema_name, payload)
+    end
+
+    def validate!(schema_name, payload)
+      return payload if valid?(schema_name, payload)
+
+      raise InvalidPayload, "#{schema_name.to_s.tr('_', ' ')} schema invalid"
+    end
+
+    def validate_render_plan!(render_plan) = validate!(:render_plan, render_plan)
+
+    def validate_pre_output!(diagnostics)
+      validate!(:diagnostics, diagnostic_document('global', nil, diagnostics))
+    end
+
+    def validate_publication!(diagnostics:, artifacts:)
+      diagnostic_documents = diagnostic_documents(diagnostics)
+      diagnostic_documents.each { |document| validate!(:diagnostics, document) }
+      each_render_plan(artifacts) { |render_plan| validate_render_plan!(render_plan) }
+      validate_diagnostic_refs!(diagnostic_documents, artifacts)
+      diagnostic_documents
+    end
+
+    private
+
+    attr_reader :schema_root, :schemas
+
+    def schema(schema_name)
+      key = schema_name.to_sym
+      schemas[key] ||= JSONSchemer.schema(JSON.parse(schema_root.join(SCHEMA_FILES.fetch(key)).read))
+    end
+
+    def attribute_identity_errors(schema_name, payload)
+      return [] unless %i[ir render_plan].include?(schema_name.to_sym)
+      return [] unless payload.is_a?(Hash) && payload['entities'].is_a?(Array)
+
+      seen = {}
+      payload['entities'].each_with_index.flat_map { |entity, index| entity_attribute_errors(entity, index, seen) }
+    end
+
+    def entity_attribute_errors(entity, entity_index, seen)
+      return [] unless entity.is_a?(Hash) && entity['attributes'].is_a?(Array)
+
+      entity['attributes'].each_with_index.filter_map do |attribute, index|
+        duplicate_attribute_error(attribute, "/entities/#{entity_index}/attributes/#{index}/attribute_id", seen)
+      end
+    end
+
+    def duplicate_attribute_error(attribute, pointer, seen)
+      return unless attribute.is_a?(Hash) && attribute['attribute_id'].is_a?(String)
+
+      attribute_id = attribute.fetch('attribute_id')
+      duplicate = seen.key?(attribute_id)
+      seen[attribute_id] = true
+      return unless duplicate
+
+      { 'data_pointer' => pointer, 'type' => 'unique_attribute_identity' }
+    end
+
+    def each_render_plan(artifacts)
+      artifacts.each_value do |domain_artifacts|
+        domain_artifacts.each_value { |artifact| yield artifact.fetch(:render_plan) }
+      end
+    end
+
+    def validate_diagnostic_refs!(diagnostic_documents, artifacts)
+      diagnostic_ids = diagnostic_ids_by_domain(diagnostic_documents)
+      artifacts.each do |domain_id, domain_artifacts|
+        allowed_ids = diagnostic_ids.fetch(nil, []) + diagnostic_ids.fetch(domain_id, [])
+        each_render_plan(domain_id => domain_artifacts) do |render_plan|
+          unresolved = render_plan.fetch('diagnostic_ids') - allowed_ids
+          raise InvalidPayload, 'render plan diagnostic_ids unresolved' unless unresolved.empty?
+        end
+      end
+    end
+
+    def diagnostic_ids_by_domain(diagnostic_documents)
+      diagnostic_documents.each_with_object({}) do |document, ids|
+        domain_id = document.fetch('scope') == 'global' ? nil : document.fetch('domain_id')
+        ids[domain_id] ||= []
+        ids[domain_id].concat(document.fetch('diagnostics').map { |diagnostic| diagnostic.fetch('diagnostic_id') })
+      end
+    end
+
+    def diagnostic_documents(diagnostics)
+      groups = diagnostics.group_by do |diagnostic|
+        diagnostic.fetch('scope') == 'invocation' ? ['global', nil] : ['domain', diagnostic_domain_id(diagnostic)]
+      end
+      groups.map do |(scope, domain_id), items|
+        diagnostic_document(scope, domain_id, items)
+      end
+    end
+
+    def diagnostic_document(scope, domain_id, diagnostics)
+      payload = {
+        'schema_version' => 1,
+        'scope' => scope,
+        'domain_id' => domain_id,
+        'diagnostics' => Ordering.sort_diagnostics(diagnostics),
+        'digest_sha256' => nil
+      }
+      payload.merge('digest_sha256' => CanonicalJson.digest_sha256(payload))
+    end
+
+    def diagnostic_domain_id(diagnostic)
+      diagnostic.fetch('metadata', {}).fetch('domain_id')
+    end
+  end
+end

data/lib/rails_mmd/subject_ids.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsMmd
+  # Normalizes diagnostic subject identifiers without treating them as free text.
+  module SubjectIds
+    PATTERN = /\A[A-Za-z0-9_:.]+\z/
+
+    module_function
+
+    def normalize(value, code:)
+      subject_id = value&.to_s
+      return subject_id if subject_id.nil? || subject_id.match?(PATTERN)
+
+      raise ArgumentError, "invalid diagnostic subject_id for #{code}"
+    end
+  end
+end

data/lib/rails_mmd/tooling_tasks.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RailsMmd
+  # Shared command builders for repository Rake tooling.
+  module ToolingTasks
+    BUNDLE_AUDIT_COMMAND = %w[bundle exec bundler-audit check --no-update].freeze
+    BUNDLE_AUDIT_UPDATE_COMMAND = %w[bundle exec bundler-audit update].freeze
+
+    module_function
+
+    def git_ref?(ref)
+      system('git', 'rev-parse', '--verify', '--quiet', "#{ref}^{commit}", out: File::NULL)
+    end
+
+    def undercover_compare_ref(default_ref)
+      env_ref = ENV.fetch('UNDERCOVER_COMPARE', nil)
+      unless env_ref.nil?
+        abort "UNDERCOVER_COMPARE does not resolve to a commit: #{env_ref.inspect}" unless git_ref?(env_ref)
+
+        return env_ref
+      end
+
+      [default_ref, 'origin/main', 'main', 'HEAD^'].find { |ref| git_ref?(ref) }
+    end
+
+    def undercover_command(config)
+      compare_ref = undercover_compare_ref(config.fetch('compare'))
+      abort 'No usable Undercover compare ref found' unless compare_ref
+
+      [
+        { 'SIMPLECOV_NO_DEFAULTS' => 'true' },
+        'bundle', 'exec', 'undercover',
+        *undercover_options(config, compare_ref)
+      ]
+    end
+
+    def undercover_options(config, compare_ref)
+      [
+        '--simplecov', config.fetch('simplecov'),
+        '--compare', compare_ref,
+        '--include-files', config.fetch('include_files'),
+        '--exclude-files', config.fetch('exclude_files'),
+        '--max-warnings', config.fetch('max_warnings').to_s
+      ]
+    end
+  end
+end

data/lib/rails_mmd/verification_runner.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RailsMmd
+  # Owns pre-commit path classification, ordering, and command selection.
+  class VerificationRunner
+    class CommandFailed < StandardError; end
+
+    RUBY_PATH = %r{
+      \A(?:
+        [^/]+\.(?:rb|rake)|Rakefile|exe/rails-mmd|bin/.+|lib/.+\.rb|
+        spec/(?:.+/)?[^/]+\.rb|features/(?:.+/)?[^/]+\.rb
+      )\z
+    }x
+    DIRECT_SPEC_PATH = %r{\Aspec/.+_spec\.rb\z}
+    FULL_SPEC_SUITE_CONFIG_PATHS = %w[.rspec .simplecov .undercover.yml].freeze
+    DEPENDENCY_PATH = %r{\A(?:Gemfile(?:\.lock)?|[^/]+\.gemspec)\z}
+    CONTRACT_PATH = %r{\A(?:schemas/.+\.json|fixtures/.+\.(?:json|mmd)|AGENTS\.md|README\.md|docs/.+\.md)\z}
+
+    # The process seam has a production adapter and recording adapters in specs.
+    class ProcessAdapter
+      def run!(*command)
+        return if system(*command)
+
+        raise CommandFailed, "verification command failed: #{command.join(' ')}"
+      end
+
+      def capture3(*command)
+        Open3.capture3(*command)
+      end
+
+      def success?(*command)
+        system(*command, out: File::NULL, err: File::NULL)
+      end
+    end
+
+    def initialize(process: ProcessAdapter.new, output: $stdout, error: $stderr)
+      @process = process
+      @output = output
+      @error = error
+    end
+
+    def run!(paths)
+      route(normalize_paths(paths))
+    rescue CommandFailed => e
+      error.puts(e.message)
+      raise SystemExit, 1
+    end
+
+    private
+
+    attr_reader :error, :output, :process
+
+    def route(paths)
+      run_ruby_checks(paths.grep(RUBY_PATH))
+      run_specs(paths)
+      run_dependency_checks(paths)
+      run_ruby_version_smoke(paths)
+      run_rubocop_config(paths)
+      run_contracts(paths)
+      report_p0_contract(paths)
+    end
+
+    def normalize_paths(paths)
+      paths.flatten.compact.map(&:to_s).reject(&:empty?).uniq
+    end
+
+    def run_ruby_checks(paths)
+      return if paths.empty?
+
+      ensure_no_mixed_changes!(paths)
+      process.run!('bundle', 'exec', 'rubocop', '--autocorrect-all', '--force-exclusion', '--', *paths)
+      ensure_no_post_repair_diff!
+      process.run!('bundle', 'exec', 'rubocop', '--force-exclusion', '--', *paths)
+    end
+
+    def ensure_no_mixed_changes!(paths)
+      mixed_paths = unstaged_changed_paths(paths)
+      return if mixed_paths.empty?
+
+      report_mixed_paths(mixed_paths)
+      raise SystemExit, 1
+    end
+
+    def unstaged_changed_paths(paths)
+      stdout, stderr, status = process.capture3('git', 'diff', '--name-only', '--', *paths)
+      raise CommandFailed, stderr unless status.success?
+
+      stdout.lines.map(&:chomp).reject(&:empty?)
+    end
+
+    def report_mixed_paths(mixed_paths)
+      error.puts('pre-commit blocked: these staged files also have unstaged changes:')
+      mixed_paths.each { |path| error.puts("  #{path}") }
+      error.puts('Stage or stash the unstaged changes before repair commands run.')
+    end
+
+    def ensure_no_post_repair_diff!
+      return if process.success?('git', 'diff', '--quiet')
+
+      error.puts('pre-commit blocked: repair changed tracked files.')
+      error.puts('Inspect the deterministic repair diff, then stage the intended changes.')
+      raise SystemExit, 1
+    end
+
+    def run_specs(paths)
+      if paths.intersect?(FULL_SPEC_SUITE_CONFIG_PATHS)
+        process.run!('bundle', 'exec', 'rake', 'coverage')
+      elsif (specs = paths.grep(DIRECT_SPEC_PATH)).any?
+        process.run!('bundle', 'exec', 'rspec', *specs)
+      end
+    end
+
+    def run_dependency_checks(paths)
+      return unless paths.any? { |path| path.match?(DEPENDENCY_PATH) }
+
+      process.run!('bundle', 'check')
+      process.run!('bundle', 'exec', 'rake', 'bundle:audit')
+    end
+
+    def run_ruby_version_smoke(paths)
+      return unless paths.include?('.ruby-version')
+
+      process.run!('ruby', '-v')
+      process.run!('bundle', 'exec', 'exe/rails-mmd', '--version')
+    end
+
+    def run_rubocop_config(paths)
+      process.run!('bundle', 'exec', 'rake', 'rubocop') if paths.include?('.rubocop.yml')
+    end
+
+    def run_contracts(paths)
+      process.run!('bundle', 'exec', 'rspec', 'spec/contracts') if paths.any? { |path| path.match?(CONTRACT_PATH) }
+    end
+
+    def report_p0_contract(paths)
+      return unless paths.include?('docs/p0-contract.md')
+
+      output.puts('docs/p0-contract.md changed; no P0 contract verifier exists yet.')
+    end
+  end
+end

data/lib/rails_mmd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsMmd
+  VERSION = '0.1.0'
+end

data/lib/rails_mmd.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'rails_mmd/version'
+require_relative 'rails_mmd/config'
+require_relative 'rails_mmd/constant_resolver'
+require_relative 'rails_mmd/domain_resolver'
+require_relative 'rails_mmd/model_inventory'
+require_relative 'rails_mmd/rails_loader'
+require_relative 'rails_mmd/relationship_builder'
+require_relative 'rails_mmd/ir_builder'
+require_relative 'rails_mmd/render_plan_builder'
+require_relative 'rails_mmd/mermaid_serializer'
+require_relative 'rails_mmd/publisher'
+require_relative 'rails_mmd/generate_command'
+require_relative 'rails_mmd/schema_probe'

data/schemas/config.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://audiostakes.example/schemas/rails-mmd/config.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "domains"],
+  "properties": {
+    "version": { "const": 1 },
+    "domains": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "allOf": [
+          { "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" },
+          { "not": { "pattern": "\\s" } }
+        ]
+      },
+      "additionalProperties": { "$ref": "#/$defs/domain" }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "directory": { "type": "string", "minLength": 1 },
+        "format": { "enum": ["er", "class", "both"] },
+        "attributes": { "enum": ["none", "keys"] },
+        "direction": { "enum": ["TB", "BT", "LR", "RL"] }
+      }
+    }
+  },
+  "$defs": {
+    "ruby_constant": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*$"
+    },
+    "domain": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["include_models"],
+      "properties": {
+        "include_models": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/ruby_constant" }
+        },
+        "exclude_models": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ruby_constant" },
+          "default": []
+        }
+      }
+    }
+  }
+}